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

Annotations already declare destructive=true, readOnly=false, openWorld=true and non-idempotent, so the safety profile is covered. The description adds genuinely new context: the dry-run default, the batch id returned for later undo, and the fallback behavior on hosts lacking a redirect store — but it doesn't say whether existing redirects are overwritten or how conflicts are handled.

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?

Four tight sentences, front-loaded with the action and scope, then preview behavior, then the fallback case, then the return value. No filler or repetition of the schema.

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 no output schema, the description correctly discloses the return (batch id) and the alternate return (nginx/Apache lines) — the two things an agent must know to act on the result. For a destructive write tool it could still say more about permissions or overwrite semantics, but the essentials are present.

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 100%, so baseline is 3; the description earns above that by adding semantics the schema lacks — 'no patterns' (one path to one address), the 301 default vs 302, and that 'to' may be a site path or a full address. It doesn't mention the required 'changes' array wrapper explicitly, but the field semantics are clear.

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+resource (write redirects) and immediately scopes it: from-path → to-path/address, code 301 or 302, into a named redirect store (Magento url_rewrite, WordPress Redirection/Rank Math). It is clearly separable from siblings like redirects_list, redirects_find, and redirects_undo.

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 concrete when-behavior (dry_run defaults to true and previews only) and routes the agent to an alternative path (returns nginx/Apache lines to use with write_file when no redirect store exists). It also points to redirects_undo for reversal, though it never explicitly says when to use redirects_find/list first to check for conflicts.

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