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

Annotations already declare readOnlyHint: true graves, idempotent, and non-destructive, but the description goes well beyond by explaining the pricing model dynamics (usage-to-date, tiered curves), the 'reprices are effective-forward' behavior, and the guarantee of consistency with the metering seam. It also clarifies exemptions (lifecycle events, never priced) and failure modes in the return shape. No contradiction with the annotations.

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 a single focused paragraph that packs a dense amount of meaning into every clause: it states the tool's purpose, the cost model, edge cases (unlisted tools, lifecycle), the existence of repricing (“Reprices are effective-forward”), the consistency guarantee (“the metering seam enforces”), and the return shape. No word is wasted, and it is front-loaded with the core value proposition.

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?

Given this is a read-only pricing tool with no parameters, no output schema, and rich annotations (readOnlyHint, idempotentHint), the description is exemplary. It explains the pricing semantics (usage-tiered curves, free-to-start, steady pricing), what is not priced, how repricing works, and the exact return structure. It even notes the return includes failure modesnewlines and platform definitions, which is more than enough context for the agent to understand when and how to invoke it.

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?

The tool has zero parameters, so there is nothing for the schema to cover beyond the empty properties object. The description confirms no arguments are needed by including 'call federation_pricesheet with arguments {}' as an example. While the baseline for a zero-param tool is 4, the description adds value by explaining what the returned structure will be (a detailed JSON format), making the zero-parameter simplicity explicit.

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 clearly states the tool's purpose: to read the federation pricesheet, which maps every platform's per-act Com prices. It explicitly specifies the resource (pricesheet) and the scope (all platforms, usage-tiered curves), distinguishing it from siblings like federation_catalog_* by focusing on pricing and lifecycle rules.

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 explicitly identifies when to use this tool (to read the current pricesheet) and provides key decision cues: tools not listed are free, lifecycle events are never priced, and the returned structure is described. It also tells the agent that this tool reflects the actual enforcement map, which is a clear reason to call it for pricing context.

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