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

Annotations only say not read-only, not destructive, not open-world. The description adds real substance beyond that: additive and low-risk, scoped to the caller's own record, undoable from the same surface, returns an ordinary result rather than a plan_token, and a stated confirmation rule. An agent knows both the blast radius and the approval semantics before calling.

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 purpose is front-loaded and the second sentence maps kinds and the downstream routing path efficiently. The confirmation paragraph is longer than needed and ends on a general policy about destructive/outbound/financial tools that is only indirectly about this tool, though it does justify the immediate-execution behavior.

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 two-parameter write tool with annotations and no output schema, the definition covers purpose, safety profile, approval behavior, and next step well enough to call correctly. The only meaningful hole is what content should contain for non-text kinds, which matters for a capture tool that accepts photo/pdf/voice.

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 is 0%, so the description has to carry parameter meaning. It does enumerate the kind enum (text/voice/link/photo/pdf) and gesture at content via "a raw thought, link, or transcript," which is genuine added meaning. However it never says what content should hold for photo/pdf/voice kinds (URL, base64, transcript text), leaving a real ambiguity for 3 of 5 enum values.

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?

"Capture something into the caller's Universal Inbox (a raw thought, link, or transcript)" gives a specific verb, resource, and payload shape. It also implicitly separates capture from the sibling route_inbox_item by saying routing happens later via note/task/event, so the agent can place it in the inbox workflow without opening the schema.

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 states the use case (capture now, triage later) and gives an explicit confirmation policy: run immediately on request because it writes only the caller's own record and is undoable, while destructive/outbound/financial actions still propose and wait. It does not explicitly contrast with list_inbox or delete_inbox_item, but the how-to-proceed guidance is unusually concrete.

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