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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations with the "(free)" cost disclosure and the exact response structure, giving the agent concrete expectations of the payload. No contradictions; the only minor gap is no mention of data-freshness windows or auth scoping for "own" beyond inference.

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?

Two tightly-scoped sentences with strong front-loading: the first gives the action and endpoint, the second the exact response contract. The compact return type notation is information-dense with zero filler. Every element earns its place; the cost qualifier "(free)" is parenthetically efficient rather than wordy.

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 simple single-parameter GET tool with strong annotations, the description is nearly complete: it covers what it does, the cost posture, the endpoint, and the exact return shape. Since no output schema exists, the inline return type fills that gap well. Minor absence of notes on result ordering, data freshness, or pagination of by_service are edge omissions for a tool this simple.

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% (the only parameter, sellerId, is documented as a 'Registered seller slug' with a pattern), so the baseline of 3 applies. The description's endpoint URL shows the parameter is path-based but adds little semantic detail beyond the schema's 100% coverage. The description does not meaningfully exceed the schema's parameter documentation—it's consistent, just not additive.

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?

"Fetch a seller's own settlement analytics" uses a specific verb+resource, further grounded by the full endpoint URL (GET /v1/sellers/{sellerId}/analytics). The scope qualifier "own" and the return shape (total_settled_calls, by_service) clearly differentiate it from siblings like code402_get_seller_invoice or code402_list_services. Explicitly identifies the exact resource and operation with no ambiguity.

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 implies use cases via the "settlement analytics (free)" qualifier and the detailed return shape, which tells the agent what kind of data to expect. However, there is no explicit statement of when to prefer this over get_seller_invoice, list_services, or other siblings, and no exclusions or alternative pointers are given. Usage context is implied rather than stated.

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