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

The description adds real value: it discloses the narrow write scope (only unread→read), the immutability of subject/body, and cross-tenant inbox context. However, 'Idempotent: re-confirming an already-read note is a no-op' directly conflicts with the annotation idempotentHint=false, which would tell a client the opposite about repeat calls; that inconsistency is the main behavioral defect.

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?

Front-loaded with the action and scope, then constraints, then a NEXT pointer — a sensible order with little waste. Some clauses ('the ONLY edit a recipient holds') are slightly rhetorical but still convey scope limits.

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?

Covers the action, mutation scope, immutability, idempotency intent, and the follow-up tool, which is solid for a one-required-param write tool with no output schema. Gaps remain around what a successful confirm returns, error behavior for a non-recipient or unknown id, and the role of the seven extra schema fields.

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 only 13%, with just `id` documented, so the description carries most of the burden. It does usefully clarify that subject/body can never be rewritten and that status is what changes, implicitly telling the agent not to supply those fields, but it never explains the remaining fields (from_tenant_id, consent_grant_id, related_entity_*).

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 and resource ('Confirm receipt of a note in your cross-tenant agent_note inbox') and immediately scopes it ('the ONLY edit a recipient holds, moving status unread to read'). This clearly separates it from agent_note_list and agent_note_read, which do not mutate state.

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?

Gives a clear next step ('NEXT: agent_note_list to see the rest of the inbox') and implies the trigger (you have received and are acknowledging a note). It does not explicitly contrast with agent_note_read, so an agent must infer that reading is a separate, non-mutating call.

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