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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without help from the description. The description contributes the endpoint path and confirms the tool is a pure estimation/optimization utility. It adds nothing about the non-obvious behavior that one endpoint bundles three distinct computations.

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?

A single front-loaded sentence that leads with the capability set and ends with the endpoint. No filler, no repetition of the title. It is short to the point of leaving the mode-selection question unresolved, which is a completeness problem rather than a verbosity one.

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?

With no output schema, the description should convey what comes back from an estimate or cost calculation, and it does not. It also omits the shape `blocks` must take and how the three advertised functions are distinguished by input, leaving real ambiguity for a three-parameter tool with two required fields.

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 100%, which sets the baseline at 3. The description's references to token estimation, context budget, and message order loosely connect to max_context_tokens and blocks, but the schema's own parameter descriptions are placeholders ("Array parameter 'blocks'"), so neither source explains the expected element shape.

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 names three concrete operations — token estimation, message reordering for prompt caching, and LLM API cost calculation — plus the endpoint POST /v1/prompt-cache-budgeter. This is specific verb+resource language that no sibling tool overlaps with (rag_chunker and llm_messages_guard address different concerns). It stops short of 5 because it never clarifies how a caller selects among the three functions from the same three-parameter surface.

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?

There is no when-to-use guidance, no mention of when not to use it, and no alternative named. An agent cannot tell from the text whether supplying `blocks` triggers the reordering mode versus merely the token estimate, so mode selection is left entirely to inference.

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