LightCMS

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

Annotations declare destructiveHint=true; the description adds critical behavioral context that the modification is 'permanent', specifies the mandatory 3-step workflow (preview, confirm, execute), and clarifies the side effects of auto_republish. Does not mention rollback capabilities or rate limits, but covers primary behavioral concerns.

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?

Front-loaded with the core function, followed by clearly demarcated 'MANDATORY workflow' steps, then specific parameter guidance. Every sentence conveys critical instruction or context; zero waste. Structure prioritizes safety-critical workflow information.

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 the destructive nature (destructiveHint:true) and lack of output schema, the description is complete. It covers the essential safety workflow, distinguishes from all relevant siblings (preview and scoped variants), and explains the primary parameters' interaction (auto_republish). No additional description text is needed for an AI to invoke this correctly.

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 100% schema coverage (baseline 3), the description adds significant value by explaining auto_republish's practical effect ('collapsing the execute + publish_multiple flow into one call') and specifying that version_comment should be 'clear' according to the workflow. Elevates beyond raw schema definitions.

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 executes a 'site-wide search-and-replace across all content' with the specific verb 'Execute' and resource 'all content'. It effectively distinguishes from siblings by contrasting with scoped_search_replace_execute ('For targeted replacements, use...instead') and implicitly from search_replace_preview by stating this 'Modifies...permanently' vs the preview's read-only nature.

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?

Provides explicit when/when-not guidance: mandates running search_replace_preview first, getting explicit user confirmation, and suggests scoped_search_replace_execute for targeted replacements. Also explains when to use auto_republish (to collapse execute + publish_multiple into one call).

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