tokenpull

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, lowering the bar, but the description adds meaningful behavioral disclosure beyond it: data scoping ('reads usage counts not message content'), privacy guarantees ('stay on your machine unless you submit them'), and explicit data-quality caveats ('estimated=true when cacheCreate isn't available', 'dataGap note when the log format doesn't expose raw token counts'). No contradiction with the readOnlyHint annotation exists — 'pull' and 'reads' align with it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each earning its place: purpose+windows, scope/cascade, privacy, and data-caveats. The structure front-loads the core purpose and moves outward to caveats. Loses one point for density in the final sentence, which crams estimated, cacheCreate, and dataGap into a single long clause that could be restructured for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-optional-param tool with a readOnlyHint and output schema present, the description covers all essential ground: what it does, what data it touches, privacy implications, and how results may degrade across platforms. The output schema handles return-value documentation, and the description rounds out the user-facing intent (rank windows with cascade, zero paste). Nothing material is left unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with the platform enum fully documented (path for devin, env var for copilot), so the baseline is 3. The description adds value by explaining what the values return in imperfect conditions ('estimated=true when cacheCreate isn't available', 'dataGap note'), which helps the agent interpret results for any platform choice, and flags platform quirks ('codex is estimated via io_ratio'). Slightly above baseline but doesn't over-perform given the schema already carries the detailed per-platform semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb+resource construction ('Pull your LOCAL token usage from the platform's session logs') combined with distinctive scope ('rank it across the four windows (7d/30d/90d/all-time)', 'cascade', 'zero paste') that differentiates it from siblings like rank_paste and tokenpull_compare. 'Token-only: reads usage counts not message content' sharpens the boundaries further. The resource, action, and scope are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when this tool is appropriate: it's the local, offline, privacy-preserving read operation ('zero paste', 'The numbers stay on your machine unless you submit them'), which contrasts implicitly with paste-based siblings. It doesn't name explicit alternatives like tokenpull_compare or rank_windows, but the local/paste-free framing plus setup caveats ('Some platforms need setup') provide solid contextual guidance for an agent choosing tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.