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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the agent knows this is an irreversible external write. The description usefully adds that the mechanism is an emailed link whose response is later recorded, but it omits that the response arrives asynchronously (requiring get_decision/wait_for_decision) and says nothing about expiry or idempotency behavior.

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 tight sentences with the core action front-loaded and the person/personId constraint appended. Nothing is padded, though the brevity is part of why the definition under-specifies.

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 an 8-parameter, nested-object, asynchronous external-side-effect tool with no output schema, the description is far too thin. It gives no account of the request lifecycle, the conditional choices field, or how the recorded response is retrieved.

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% across 8 parameters, so the description carries the full burden and fails to. Only person/personId are mentioned, and the description never explains kind vs choices coupling, the purpose of expiresAt, or the idempotencyKey, leaving five required parameters undocumented in prose.

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: emails a person a decision link and records the response. That is distinguishable in substance from siblings like send_approval_request or create_approval_request, but the description never names those siblings or explains the boundary, so the agent must infer which tool routes to a person versus an approval flow.

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?

'Provide one person or personId' is a parameter constraint, not usage guidance. There is no statement of when to use this versus send_approval_request, create_approval_request, or wait_for_decision, and no prerequisites or exclusions are given.

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