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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds genuinely non-obvious behavior: actions replace rather than merge, so partial payloads silently drop steps. It also explains why visibility is non-optional (saving always writes it). It stops short of describing permissions or error 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 short sentences, front-loaded with the verb and immediately followed by the destructive gotcha, then the required-field caveat. No filler; only the terse first sentence is thinner than it could be.

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 destructive mutation with no output schema and full annotation coverage, the description supplies the one behavior that most often causes data loss (replace-not-merge). Remaining gaps — whether name is optional and left unchanged, and any auth requirements — are minor.

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?

With schema description coverage at only 50%, the description compensates by explaining that actions is a full replacement list and why visibility is required — semantics the enum and types alone do not convey. macro_id and name are left to the schema, but neither carries hidden meaning.

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?

Clear verb+resource ("Change a macro") that an agent can distinguish from a read or creation operation. It does not, however, differentiate against the obvious siblings create_macro, delete_macro and execute_macro, so the boundary must be inferred from the name alone.

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?

Usage is implied by "Change a macro" (modify an existing macro rather than run it), and the description gives an important how-to-call caution about full replacement. But it never states when to prefer this over execute_macro or create_macro, nor any prerequisite such as needing the macro to already exist.

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