You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Reduce token usage in write-operation schemas (read-only fields + user $ref bloat) #438
The tool schemas for write operations (move-rename-onedrive-item, create-onedrive-folder, etc.) include many
fields that are read-only on Graph PATCH/POST and never accepted in request bodies. Combined with full user $ref
expansions for createdByUser/lastModifiedByUser, this inflates the schema payload that LLM clients load into
context — roughly 3,000+ tokens per affected tool.
Related to #434 — same spirit, focused on the body-schema side.
Problem 1: Read-only fields in PATCH/POST body schemas
move-rename-onedrive-item body currently includes createdByUser, lastModifiedByUser, createdDateTime, eTag, cTag, audio, bundle, pendingOperations, etc. Per Graph docs, the only writable fields on PATCH /drives/{id}/items/{id} are:
name
parentReference (specifically id and driveId)
fileSystemInfo (createdDateTime / lastModifiedDateTime — used for migration)
@microsoft.graph.conflictBehavior
Everything else is silently ignored or rejected.
create-onedrive-folder body similarly only needs:
name
folder (empty object marker)
@microsoft.graph.conflictBehavior
Problem 2: user $ref bloat in createdByUser / lastModifiedByUser
The user resource type inherits from directoryObject and pulls in ~25 properties including assignedLicenses, assignedPlans, authorizationInfo, customSecurityAttributes, etc. For a file-management tool's createdBy.user,
only id, displayName, and email/userPrincipalName are useful. This $ref appears in many response schemas
across the toolset, so the bloat compounds.
Estimated impact
Per affected write-tool schema: ~2,000–3,000 tokens saved
Across all tools that reference the user schema: ~1,500 tokens each
For a typical session loading the full toolset, easily 10k+ tokens
Suggested fix
Auto-generation from the Graph OpenAPI spec is convenient but pulls in everything. Two options:
Maintain a writable-fields allowlist per endpoint and filter the generated body schemas against it.
Define trimmed schemas manually for the write operations (small surface, ~6 endpoints).
Lower-priority follow-ups (separate issues if you want)
Default $select hint in tool descriptions for list/get calls (response-side savings, ~500–1500 tokens per call).
Shorten verbose parameter descriptions like fetchAllPages.
This is a good idea, but from what I can see MS doesn't tag fields as read-only. They only type out "Read-only" in description. A bit flaky perhaps, but we could give it a try - unless you have a better idea?
And what about upsert - and there can we times when MS backends expect to read a value used for insert/update, how sure are we these are never used?
Good questions from the maintainer. A few thoughts:
Read-only detection: You're right that MS Graph relies on description text. A practical approach: parse the OpenAPI spec for descriptions matching regex patterns like 'read.?only|computed|automatically|cannot be set' (case-insensitive). This is fragile but beats regex on raw descriptions.
Upsert safety: The risk is real—some endpoints accept fields on INSERT that are read-only on UPDATE, and vice versa. Safest mitigation: maintain an allowlist per endpoint rather than assuming all fields are safe to omit. The 6-endpoint surface is small enough to hand-verify once.
--discovery flag: Have you measured context token reduction with discovery-style queries vs. full schema loading? If discovery provides significant savings, that might be a better lever than schema trimming for the common case.
For #438 specifically: I'd suggest starting with the allowlist approach on the 6 write endpoints (move, rename, create-folder, etc.), hand-verify against Graph docs once, then auto-generate list operations without trimming. That gives you confidence + wins on both token and correctness fronts.
@daveCode-dot you ask if I have done measurements of --discovery - I have done some, and it goes from like 200k to 1k tokens.
But loading tools will bump the numbers up again, per tool... so it depends on how it is used.
200k → 1k is a 200x reduction — that's not a marginal optimization, that's the right default for any agent loading more than a handful of tools.
Looking at src/mcp-instructions.ts and src/lib/tool-schema.ts, the lazy pattern is already wired (search-tools → get-tool-schema → execute-tool). The remaining question is the break-even: at how many loaded tools does the incremental schema cost match the cost of the full upfront load? Rough math from your numbers: ~3.1k tokens per tool average (199k delta / 64 ref-heavy tools), so the crossover is around 60-65 tools loaded in-session before discovery loses its edge.
Two things that would harden the pattern further:
Telemetry: log per-session count of get-tool-schema calls. If the median session loads 80+ tools, discovery is hurting; if median is <20, it's a massive win and worth defaulting on.
Soft cap: if discovery load count crosses ~50 in one session, surface a warning that pre-loading would have been cheaper at this point. Lets users self-correct without forcing the choice.
The allowlist approach from my earlier #438 comment is orthogonal — still useful for the 6 write endpoints whether or not discovery is on, since read-only field bloat eats from the per-tool schema budget too.
Activity
eirikb commentedon May 6, 2026
Hi
This is a good idea, but from what I can see MS doesn't tag fields as read-only. They only type out "Read-only" in description. A bit flaky perhaps, but we could give it a try - unless you have a better idea?
And what about upsert - and there can we times when MS backends expect to read a value used for insert/update, how sure are we these are never used?
Also - have you tried
--discovery?daveCode-dot commentedon May 14, 2026
Good questions from the maintainer. A few thoughts:
Read-only detection: You're right that MS Graph relies on description text. A practical approach: parse the OpenAPI spec for descriptions matching regex patterns like 'read.?only|computed|automatically|cannot be set' (case-insensitive). This is fragile but beats regex on raw descriptions.
Upsert safety: The risk is real—some endpoints accept fields on INSERT that are read-only on UPDATE, and vice versa. Safest mitigation: maintain an allowlist per endpoint rather than assuming all fields are safe to omit. The 6-endpoint surface is small enough to hand-verify once.
--discoveryflag: Have you measured context token reduction with discovery-style queries vs. full schema loading? If discovery provides significant savings, that might be a better lever than schema trimming for the common case.For #438 specifically: I'd suggest starting with the allowlist approach on the 6 write endpoints (move, rename, create-folder, etc.), hand-verify against Graph docs once, then auto-generate list operations without trimming. That gives you confidence + wins on both token and correctness fronts.
eirikb commentedon May 14, 2026
@daveCode-dot you ask if I have done measurements of --discovery - I have done some, and it goes from like 200k to 1k tokens.
But loading tools will bump the numbers up again, per tool... so it depends on how it is used.
daveCode-dot commentedon May 15, 2026
200k → 1k is a 200x reduction — that's not a marginal optimization, that's the right default for any agent loading more than a handful of tools.
Looking at
src/mcp-instructions.tsandsrc/lib/tool-schema.ts, the lazy pattern is already wired (search-tools→get-tool-schema→execute-tool). The remaining question is the break-even: at how many loaded tools does the incremental schema cost match the cost of the full upfront load? Rough math from your numbers: ~3.1k tokens per tool average (199k delta / 64 ref-heavy tools), so the crossover is around 60-65 tools loaded in-session before discovery loses its edge.Two things that would harden the pattern further:
get-tool-schemacalls. If the median session loads 80+ tools, discovery is hurting; if median is <20, it's a massive win and worth defaulting on.The allowlist approach from my earlier #438 comment is orthogonal — still useful for the 6 write endpoints whether or not discovery is on, since read-only field bloat eats from the per-tool schema budget too.
eirikb commentedon May 15, 2026
@daveCode-dot I uh... that sounds like a lot. Can't we just keep everything as-is?
And I'm not too keen on starting telemetry. I considered it long ago, because it's technically easy, but the responsibility isn't.
eirikb commentedon May 18, 2026
Closing in favor of just using
--discoverywithout being a busy bee about it. Feel free to re-open