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

With no annotations, the description carries the full behavioral burden and does so: it discloses the measurement lag (results at 7, 14 and 28 days, compared to the same pre-period), describes the return payload (record id plus the dates the 14- and 28-day results land), states cost ("Free; works on every plan"), and names a hard prerequisite with its degraded-mode consequence ("Needs Search Console connected... without it the change is logged but never measured"). That prerequisite-plus-failure-mode detail is exactly the context an agent cannot infer from the schema.

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 purpose and every sentence carries information that is not duplicated elsewhere — trigger, parameter style, return shape, cost, and prerequisite. It runs as one dense block and mixes invocation guidance with result-reading guidance, but there is no filler or restatement 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?

There is no output schema, so the description must describe returns — and it does (record id and the 14/28-day result dates). For a simple four-parameter logging tool, the prerequisite warning plus the pointer to Change_Impact closes every gap an agent needs to call it correctly and set expectations about measurement.

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, and the description earns one better by adding usage-level meaning: what_changed should be "a short plain sentence" with a concrete example ("Rewrote the title to lead with the price"), and keywords should be passed only "for the searches the change was aimed at, if they said which." It also ties site_id provenance to My_Sites, though it leaves the format of that id to the schema.

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?

Specific verb plus resource: "Log a change the caller made to a page" followed by the exact measurement it enables (clicks, impressions, position at 7/14/28 days vs. the prior baseline). It is clearly separable from Change_Impact, which it explicitly names as the read-back tool, so an agent can distinguish logging from reporting 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?

The invocation trigger is explicit: "Call it when the caller says they just changed, rewrote, added or fixed something on a page," and the follow-up tool is named ("Read the results with Change_Impact"). There are no exclusions, though — nothing about not logging planned changes, duplicate logging of the same change, or what to do when the caller is unsure a change happened.

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