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

Even though annotations already mark this as read-only, idempotent, and non-destructive, the description adds substantial behavioral context: the deprecation alias window, server-chosen source and facility, handling-version distinction from OCR context_version, Vault unavailability, and shared authorization semantics with REST. It provides far more transparency than the annotations alone.

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 dense and information-rich, with the deprecation notice front-loaded, but it is presented as a long run-on paragraph of semicolon-separated caveats. Every clause adds real information, yet the lack of structural separation makes it harder for an agent to parse quickly. A sectioned format for deprecation, gating, auth, and behavior caveats would improve it.

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 the tool's complexity, the description covers all critical context: deprecation status, replacement path, gating constraints, auth requirements, server behavior exceptions, and shared REST semantics. An output schema is present, so return-value documentation is not the description's burden. Few gaps remain for invoking this tool correctly.

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 coverage for the only parameter, item_id, is 0%, and the description does not compensate by explaining what item_id represents, how it relates to get_inbound_item, or what kinds of values are valid beyond the UUID pattern. The URI fragment '/agent-inbox/:id' hints that id maps to item_id, but the description never explicitly connects them, leaving the parameter semantics under-specified.

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 identifies the resource and action: read agent-inbox handling capabilities, version, and history. It also names the replacement tool, get_inbound_item, which helps distinguish it from siblings. The main weakness is that the exact scope of 'handling' is somewhat broad, and it does not explicitly contrast with adjacent get_agent_inbox_* 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 opens with 'Deprecated: use get_inbound_item', giving explicit direction away from this tool. It also states precise gating conditions (private-mail Live and member-sample Sandbox only), required scopes, agent-scoped bearer key requirements, and a firm directive not to substitute keys or other mail APIs after denial. This is exemplary when-to-use versus when-not-to-use guidance.

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