seo_tag_geography

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers async execution (~1–2 min), credit usage (unless dryRun), idempotent skipping of already-tagged keywords, retag and dryRun semantics, the return shape {operationId, status}, job result fields (tagCounts, ambiguousKeywords, costUsd), and polling via get_job. This is comprehensive and goes far beyond a basic 'classifies and writes tags' statement.

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?

The description is long but each sentence contributes useful information: the tag vocabulary, async timing, credit usage, return and polling flow, job result fields, idempotency, dry-run option, and follow-up tools. It is front-loaded with the core purpose and then adds operational specifics without repeating schema content. Slightly streamlined, but no waste.

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 no output schema and no annotations, the description provides a complete operational picture. It specifies the immediate return {operationId, status}, the job result structure (tagCounts, ambiguousKeywords, costUsd), the polling mechanism via get_job, error states (failed/partially_failed/cancelled), and the follow-up tools. It also explains idempotency and dry-run semantics, making it sufficient for an agent to use 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?

All three parameters (retag, dryRun, brandId) are already fully described in the schema (100% coverage), so the description doesn't need to reintroduce them. The description adds value by explaining how retag and dryRun alter behavior, e.g., 'pass retag:true to force re-classification' and 'dryRun:true to get the full classification breakdown WITHOUT writing any tags', which contextualizes the schema and gives practical guidance.

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 opens with 'Geo pivot Stage 1. Async — classifies every keyword's geographic intent and writes a `geo:*` tag into userTags.' This specifies the action (classifies and writes tags), the resource (keywords' geographic intent), and the output location (userTags), distinguishing it from sibling SEO tools like seo_categorize.

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 description provides clear workflow context: it's 'Stage 1' of a geo pivot, recommends using dryRun 'first to review tagCounts and ambiguousKeywords before committing', and explicitly names follow-up tools (seo_list_keywords or seo_list_keyword_ids with hasTag=...) for selecting tagged keywords. However, it doesn't explicitly state when not to use this tool or name alternative tools for geographic intent classification.

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