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

Annotations cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=false) but not cost or lifecycle. The description adds real context: output is saved as DRAFTS for owner review, execution is slow (minutes for a big batch), and it waits and returns per-target results. It does not spell out duplicate-creation risk on re-run despite idempotentHint=false, which is the one notable gap.

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 with no waste: the core action first, then the behavioral cost/lifecycle note, then the alternative routing. Front-loaded and every sentence earns its place.

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 usefully notes it returns per-target results, which is the key return-shape information. For an 11-param batch mutation tool it could still say more about partial failures or permissions, but the draft lifecycle, latency and alternative are all covered.

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 description coverage is 55% with 11 parameters, so the schema carries much of the load. The description adds meaning for targets (the town/product/event each page is rewritten for) and implies templatePageId is the cloned source, but leaves slugPattern, titlePattern, stripPhrases, generateFeaturedImage and baseKeyword unexplained. Marginal value beyond the schema, so baseline 3.

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 precise verb and resource chain: clones the template page once per target, rewrites each for its town/product/event, and saves them as drafts. It explicitly distinguishes itself from publish_location_pages, so an agent can tell the two apart without opening either schema.

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 an explicit routing rule: use this for drafts, use publish_location_pages to publish live instead. The condition that selects the alternative is stated rather than left to inference. The only minor omission is that sibling preview_location_pages is not named, but the primary decision branch is fully covered.

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