Skip to content

Reduce token usage in write-operation schemas (read-only fields + user $ref bloat) #438

Closed

Description

@fay28

Summary

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:

  1. Maintain a writable-fields allowlist per endpoint and filter the generated body schemas against it.
  2. 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.

Activity

  1. eirikb commented on May 6, 2026

    @eirikb
    Contributor

    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?

  2. daveCode-dot commented on May 14, 2026

    @daveCode-dot

    Good questions from the maintainer. A few thoughts:

    1. 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.

    2. 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.

    3. --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.

  3. eirikb commented on May 14, 2026

    @eirikb
    Contributor

    @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.

  4. daveCode-dot commented on May 15, 2026

    @daveCode-dot

    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:

    1. 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.
    2. 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.

  5. eirikb commented on May 15, 2026

    @eirikb
    Contributor

    @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.

  6. eirikb commented on May 18, 2026

    @eirikb
    Contributor

    Closing in favor of just using --discovery without being a busy bee about it. Feel free to re-open

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions