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

Annotations declare the mutation/idempotency/open-world profile, and the description adds real context beyond them: approval has a public side effect (publishes the supporter unless hidden is set), and the reply is publicly published and can be refused by a word filter. The remaining gap is error semantics for already-approved or invalid supporters, which the idempotentHint partly covers.

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?

Three tight sentences, front-loaded with the action, then the side effect, then the safety rule. No sentence is filler and each contributes information the agent needs.

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 an output schema present, return values need no explanation, and annotations plus the description cover the safety profile and the publication/reply behaviour. The only shortfall is not connecting 'id' to its source tool or describing the failure mode when the supporter was already approved.

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 67% and both 'reply' and 'hidden' already carry descriptions, so the description's mention of them ('unless hidden is set', 'a thank-you reply can be sent at the same time') largely restates structured data. It adds no meaning for the undescribed required 'id' (e.g., that it must come from list_pending_supports).

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 ('Approve one supporter') and scopes it to a single record, which implicitly separates it from the sibling bulk_approve_supports. An agent can distinguish it from related tools without opening any 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?

Gives an explicit precondition ('after the creator has found the payment in their own bank app') and an explicit prohibition ('never approve on their behalf without being asked to'). It also implies the alternative route by scoping to a single supporter, so both when and when-not are covered.

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