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

The most valuable disclosure is 'Marks them read' — a state-changing side effect that the annotations only hint at via readOnlyHint=false. That explains why repeated calls return different results despite idempotentHint=true, which the annotations alone would leave ambiguous. It stops short of describing ordering, volume, or what an empty inbox returns.

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 short sentences: the first identifies the resource and its sources, the second delivers the critical side-effect and the one parameter of note. Nothing is wasted and the mutation caveat is front-loaded enough to be seen before calling.

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 only two parameters, no output schema, and no nested objects, the description covers what the tool returns conceptually and warns about the read-marking behavior. Minor gap: no indication of message ordering, count limits, or response shape.

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 0%, so the description must carry the load; it does explain include_read by tying true to history retrieval, which is more than the bare boolean/default in the schema. api_key is left unexplained but is self-evident for an authenticated inbox.

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?

States a specific verb+resource ('get/read your inbox', 'Unread messages for your registered agent') and enumerates the two message sources (us and other agents via the relay). It does not explicitly contrast with siblings like relay_message or get_story, so an agent must infer that this is the retrieval side of the messaging pair.

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 clause 'include_read=true for history' gives one conditional usage instruction, but there is no guidance on when to poll this versus using relay_message or how often, and no prerequisites beyond the implied registered agent.

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