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

Annotations already declare readOnly=false, destructive=true, idempotent=true, openWorld=true, and the description adds real behavioral context: matching is done by keyword text, ranking_url is ignored unless it is on the site's own domain, and Xyle records rather than generates classifications. It never spells out what a re-run overwrites for already-classified keywords, which is the main gap against the destructive hint.

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 action, then definitions, example, matching behavior, and trigger, in a logical order. Dense but almost every clause carries information; it is on the long side but contains no padding.

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 2-parameter, high-coverage mutation tool with no output schema, the description covers field semantics, invocation format, matching behavior, correction semantics, and a trigger. It omits return-value expectations and permission/auth requirements, which keeps it short of fully complete.

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?

Despite 100% schema coverage, the description supplies semantics the schema lacks — there are 0 enums in the schema, yet the description defines allowed intent values (informational/commercial/transactional/navigational), funnel_stage meanings (tofu/mofu/bofu), cluster_name conventions (2-4 words, reused, aim 5-15 clusters), and a concrete JSON payload example. This meaningfully exceeds the schema baseline.

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 — storing your own keyword classification onto a brand's tracked keywords — and draws a clear boundary against the agent's own reasoning ('Xyle records — it does not classify for you'). This distinguishes it from add_tracked_keywords and assist_classify_keywords, which an agent could otherwise confuse it with.

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 concrete triggers: 'run after adding keywords or when get_keyword_funnel reports unclassified ones,' and names get_site_journeys as the signal for using ranking_url to correct a mapping. It stops short of explicitly excluding the similar assist_classify_keywords sibling, so the agent must infer when to prefer one over the other.

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