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

Annotations add idempotentHint=true, but the description explains exactly what that means operationally ('Exact retry key/scenario reuses the fixture'). It also discloses the deprecation state, the auth model, shared rollout switches, SQL authorization sharing with REST, and the fact that fixtures deliberately exclude real mail, charges, facility tasks, PMBs, model calls, and member samples. None of it contradicts 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 prose is dense and ordered effectively: deprecation status first, then purpose, key constraints, exclusion scope, auth, shared-state caveats. It is slightly long and contains some overlapping security statements, so it is not maximally concise, but every sentence contributes operational context.

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 an output schema present and annotations already carrying idempotency and non-destructive hints, the description fills the important gaps: deprecation lifecycle, exact endpoint, auth prerequisites, behavioral boundaries, retry semantics, and shared execution environment. Nothing an agent needs to invoke it correctly appears to be missing.

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 input schema has 0% description coverage, but the description compensates for the scenario parameter by naming the two allowed fixture types and for the idempotency key by describing retry-key reuse semantics. It does not repeat the schema's required/pattern constraints or formally label the idempotency_key, but enough meaning is added to make the parameters actionable.

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 ('Explicitly seed an isolated provider-free two_page_letter or needs_review fixture') with the exact endpoint (/v1/agent-inbox/sandbox/seed) and scenario values. It also narrows the operation by saying what it is not (no member sample, real mail, model call, etc.) and by restricting to sandbox agent keys, which separates it from the many read-only agent-inbox and mail-related siblings.

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?

It gives explicit usage context: this is a deprecation-only fixture seeding endpoint, used to test reads/reports rather than handling. It provides hard when-not guidance ('Never substitute another key or mail API after denial') and makes key/scenario eligibility explicit, including the required agent.inbox.read scope and the prohibition on member/facility keys.

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