token_report

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

With no annotations provided, the description carries the full burden and does so well. It discloses that the estimate is deterministic, uses a chars/4 heuristic, is English-prose oriented, is not a measured cost, and includes caveats about recall-call costs and snippet truncation adding tokens back. This is thorough behavioral disclosure for a read-only estimation tool.

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?

The description is front-loaded with its core purpose and then layers important caveats. It is longer than average, and the two 'NOT' clauses are somewhat redundant, but every sentence carries meaningful guidance, so the length is justified.

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 tool with no output schema and no annotations, the description provides a strong mental model of what the tool computes and what it does not. The main gap is that it does not describe the actual return shape, such as whether the output is a ratio, percentage, or raw size estimate, which an agent would need for downstream interpretation.

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 description coverage is 0%, so the description must compensate for the two parameters. It conveys that 'query' is tied to a top-k recall and that 'k' corresponds to the number of hits considered, but it never directly addresses query syntax or k's exact role beyond the phrase 'same k hits.' Some inference is still required.

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 states a specific action and resource: a deterministic payload-size estimate comparing compact projections against full records for the same top-k recall. It also proactively distinguishes itself from a whole-store comparison and from measured token/cost savings, so an agent can separate it from related recall/reporting tools.

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 to use the tool: rough payload sizing for identical recall results. It also explicitly excludes common misuses, such as comparing against dumping the entire store or claiming measured savings. It does not name specific alternative sibling tools, but the exclusions are strong enough for an agent to select it appropriately.

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