eds_fix_redirect

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

With no annotations provided, the description carries the full burden. It discloses idempotency ('updates a rule for an existing source, never duplicates'), the safe-writes path with dry-run and undo, the publish behavior ('publish:true publishes the sheet so redirects go live'), and the token requirement ('Requires EDS_DA_TOKEN'). This is thorough and gives the agent a clear behavioral model.

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?

The description is dense but every sentence serves a purpose: purpose, rule format, idempotency, safe-writes/publish, token, and pairing. It is front-loaded with the main verb and resource, then efficiently delivers all critical operational details without fluff.

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?

Given no annotations and no output schema, this description compensates fully. It covers prerequisites, safe-write behavior, live publication, and integration with eds_audit_site. The only minor omission is explicit mention of maxItems (500) and the undo mechanism's exact nature, but the schema already documents maxItems and the safe-writes mention suffices for an agent.

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 the baseline is 3. The description adds value by explaining the redirects array can contain 'one or many' rules, gives concrete examples of source/destination formats, and clarifies the idempotent update behavior. It also ties the publish parameter to actual publication, which the schema already hints at but the description contextualizes.

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?

The description clearly states the tool's purpose: 'Fix broken links (404s) by adding redirect rules to the site's redirects sheet — the EDS mechanism that serves 301 redirects.' It names a specific verb ('Fix'), resource ('redirects sheet'), and mechanism ('301 redirects'), distinguishing it from read-only siblings like eds_get_redirects.

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?

The description provides clear usage context: it pairs with eds_audit_site to identify 404s and recommends 'dry-run + undo' via the safe-writes path. It doesn't explicitly say when not to use the tool or name alternatives, but the pairing and dry-run guidance offer strong situational cues.

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