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

Annotations already flag destructiveHint=true and idempotentHint=true; the description adds precisely what the annotations cannot say — that the call OVERWRITES the existing array wholesale rather than merging, and that it returns a count. It also explains the downstream effect (rules transform individual g:* fields in the served XML), which matters for judging consequences.

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 sentences, zero padding, with the destructive mutation front-loaded. The short 'Returns the count' clause adds useful information at minimal cost.

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 full-array replacement with no output schema, the description covers the essential risks: what gets destroyed, the read-first workflow, and the return value. The remaining gap is semantic (whether rule order matters, whether rules referencing absent fields are dropped), which the agent must infer.

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?

Top-level schema coverage is 50% (feedId has no description), but the nested rule schema is densely documented, so the description's job is to add meaning beyond structure — and it does, by naming the concrete transforms (title truncation, brand prefix, removeSuffix for the title-eats-description bug, stripHtml, formatPrice). It does not explain rule ordering or interaction between rules, which is where an agent is most likely to go wrong.

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 — 'Replaces the entire fieldRules array on a feed' — which an agent can act on immediately. What it does not do is distinguish itself from the sibling update_filter_rules, which is a parallel concept an agent could easily confuse with field rules.

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 a concrete pre-condition ('Read with get_feed first if you want to append') and lists common use cases that show when this tool is the right choice. It stops short of stating when not to use it, e.g. routing to update_filter_rules for filtering behavior rather than field output.

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