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

Beyond the annotations (readOnlyHint: false, destructiveHint: false), the description details crawling behavior, URL restrictions, file/count caps, cross-origin handling, and the effect of crawlAssets. This substantially informs the agent of important traits, with no contradiction to annotations.

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 front-loaded with the core purpose, then organized into clear sections. However, the extensive list of user phrases is somewhat verbose and could be condensed, slightly reducing conciseness.

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, the description covers most aspects: behavior, restrictions, caps, and result as a 'working hosted copy'. It lacks explicit mention of what the tool returns (e.g., hosted site URL), but otherwise meets the needs for a cloning tool.

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 parameters are described in the schema (100% coverage), but the description adds meaningful context—explaining the crawlAssets default and effect, URL restrictions, and filename default. This enriches understanding beyond the 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 clones a public web page into a hosted site, specifying the action (clone), resource (public web page), and outcome (hosted copy). The 'USE THIS WHEN' section and contrast with recreation from memory effectively differentiate it from sibling tools like create_site.

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 explicit user query examples indicating when to use this tool, and warns against using it for polished/researched sites, directing to webzum.com instead. It also advises not to recreate pages from memory, offering clear guidance on alternatives.

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

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

Annotations indicate destructiveHint=true (write operation). Description adds critical behavioral details: background page generation, progress checking with get_site_status, auth via API key, and return value (businessId). No contradictions.

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?

Description is long but well-structured with bullet points and front-loaded key information. Every sentence adds value, though it could be slightly more concise without losing clarity.

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 tool's complexity and lack of output schema, the description covers purpose, usage, authentication, async behavior, progress checking, and return value. It is sufficiently complete for an AI agent to understand how to invoke and use the tool.

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?

Input schema has 100% coverage with descriptions for both parameters. The description adds context: the candidate must come from search_businesses and is the promoted business. This adds meaning beyond the schema, but the schema already does a good job.

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 explicitly states the tool creates a third-party lead-generation page, distinguishing it from creating a site for the business itself. It uses specific verbs and resources, and contrasts with sibling tool create_site.

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 clear when-to-use guidance: 'Use this when the goal is to drive qualified search traffic to someone else’s business.' Includes differences from create_site, authentication requirements, and source of input (search_businesses).

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

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

Adds details beyond annotations: authentication via API key, background generation, and return of businessId. Annotations indicate destructiveHint=true, consistent with creation. No contradiction.

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?

Five sentences, each purposeful: core action, prerequisite, authentication, async behavior, and return value. No fluff.

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?

No output schema, but description explains return value (businessId). Covers prerequisites, async nature, and companion tool. Complete for this tool's complexity.

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% with descriptions for both parameters. The description adds value by emphasizing use of the '_raw array' and stating the return of businessId, which is not in 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?

The description clearly states 'Create a new website for a business', providing a specific verb+resource. It distinguishes from siblings like create_lead_gen_site by specifying it uses a business candidate from search_businesses.

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 explicitly instructs to 'Pass a business candidate object from search_businesses' and notes the background process with progress checking via get_site_status. It gives clear context but does not explicitly mention when not to use it.

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

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

Annotations set readOnlyHint=false and destructiveHint=true, which is consistent with a creation tool. The description adds value by disclosing authentication requirements (API key), asynchronous background generation, and the need to use get_site_status to check progress, beyond what annotations provide.

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 front-loaded with the purpose and overall well-structured. However, it includes a bullet list of features that could be trimmed without loss of essential information, slightly reducing conciseness.

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 tool's complexity (21 parameters, no output schema), the description adequately covers purpose, usage scenario, auth, async behavior, and related tools. It lacks detail on return values or error cases, but the completeness is satisfactory.

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?

The input schema has 100% description coverage, so the schema already documents all parameters. The tool description does not add significant meaning beyond listing high-level features (SEO, lead capture, etc.), which is insufficient to raise the score above 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?

The description uses a specific verb ('Generate') and resource ('local SEO-optimized landing page'), clearly indicating it creates geo-targeted pages. It distinguishes from siblings like 'create_site' by emphasizing location-specificity and lead generation.

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?

It states when to use ('when you have pre-researched business data') but does not explicitly exclude alternative tools or provide direct comparisons to siblings like 'create_lead_gen_site'. Usage context is implied, not explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it lists files in the 'current version', but no further behavioral details (e.g., pagination, error handling) beyond what annotations provide.

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?

Two concise, front-loaded sentences with no wasted words.

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?

Despite no output schema, the tool is simple (1 param, read-only). The description explains the purpose adequately but could mention what the list contains (e.g., file details).

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 description adds little beyond the schema. It provides context that the businessId refers to a hosted site, but no additional parameter semantics.

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 verb 'list' and the resource 'files in a hosted site's current version', distinguishing it from sibling tools like 'host_file' (upload) and 'get_site_status' (status check).

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 says 'Use this to see what's been uploaded', implying when to use (to view uploaded files). However, it does not explicitly exclude alternatives or mention when not to use it.

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

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

Beyond readOnlyHint and destructiveHint annotations, the description details return fields (stage, overallProgress, stageProgress, message, isComplete), polling behavior, and the stop condition. No contradiction with annotations.

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?

Concise yet comprehensive: one sentence for purpose, a bulleted list of return fields, and two usage instructions. Every sentence contributes meaningfully.

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?

Despite no output schema, the description fully explains return values and polling behavior. For a status-checking tool, it covers all necessary details for correct use.

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 has 100% coverage, but description adds value by stating versionId is preferred and businessId is a less detailed fallback, enhancing the schema descriptions.

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?

Description clearly states 'Check the status and generation progress of a site', providing a specific verb and resource. It distinguishes itself from siblings like create_site or host_file, which have different purposes.

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?

Explicitly recommends using versionId from create_site for progress tracking, suggests polling every 5-10 seconds, and indicates when to stop polling (isComplete=true). Also mentions businessId as a fallback.

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

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

Annotations provide minimal behavioral info (readOnlyHint=false, destructiveHint=false). The description adds critical context: file goes live immediately, creates version history, supports specific types, max size 10MB, and base64 encoding requirement.

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 front-loaded with the main action, uses bullet points for supported types and constraints, and contains no superfluous 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?

Covers most essential details for using the tool, including immediate effect, versioning, file types, size limit, and encoding. Lacks explicit mention of prerequisite (need an existing hosted site) but is implied.

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% with good param descriptions. The description reinforces base64 encoding and provides examples for filename (path format), adding value beyond 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?

The description clearly states 'Add a file to your hosted site' with a specific verb and resource. It distinguishes from siblings like host_site (create site) and get_hosted_files (list files) by focusing on uploading individual files.

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 implicitly indicates when to use (to add a file) but lacks explicit when-not-to-use or alternative tool mentions. However, the context from sibling names makes it clear.

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

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

Annotations already indicate non-readOnly and non-destructive. The description adds significant context about the tool's role in the hosting workflow (call first, then host_file) and the psychological impact of live URLs. However, it does not disclose potential limits like site name conflicts, storage quotas, or error conditions, which would elevate transparency further.

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 excessively long with redundant motivational passages (e.g., the all-caps section about customer trust). While structured with headings, it could be reduced to 1-2 concise paragraphs. The verbosity detracts from quick comprehension for an AI agent.

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, the description adequately mentions returns (businessId and live URL) but omits details like URL format, behavior on duplicate site names, and error handling. It covers use cases well but lacks technical completeness for a creation tool.

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 schema already documents all parameters. The description adds no additional meaning beyond the schema, such as examples or default behaviors. It does imply a workflow ordering (this tool first, then host_file), but that is process guidance, not parameter semantics.

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 verb and resource: 'Instantly host any web content on WebZum.' It specifies the output (businessId and live URL) and contrasts with sibling tools like host_file and get_hosted_files. The purpose is unmistakable and specific.

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 explicit when-to-use scenarios: 'ANY TIME you generate web content' and lists user phrases that should trigger the tool ('host this', 'deploy this'). It also explicitly tells when not to use (if user declines) and directs to use this INSTEAD of other hosting services. This is thorough guidance.

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

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

Annotations only provide readOnlyHint false and destructiveHint false. The description adds significant behavioral details: zipContent format, validation rules (filename safety, extension allowlist, 10MB limit), all-or-nothing on validation failure, and upsell guidance. No contradictions.

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?

Six sentences, each earning its place. Front-loaded with purpose, then usage guidance, parameter detail, behavior, and upsell. No fluff.

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?

Tool has two parameters and no output schema. Description covers purpose, usage, behavior, and constraints. For a simple upload tool, it is complete. Could optionally mention success response, but not required.

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% with descriptions. The description adds context beyond schema: explains zipContent as 'standard base64', mentions validation and file size limit, and all-or-nothing behavior. This provides meaningful addition 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?

The description clearly states 'Upload a zipped bundle of files to a hosted site in a single call.' The verb 'upload' and resource 'zipped bundle of files' are specific. It distinguishes from sibling tool host_file by highlighting multi-file vs single-file, cost, and version benefits.

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?

Explicitly states when to use: 'Use this when you have a multi-file project... one host_zip call is far cheaper than N host_file calls...' Also implies all-or-nothing validation behavior. No explicit exclusions or alternatives beyond referencing host_file, but context is clear.

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

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

Annotations already indicate read-only and non-destructive. Description adds return format and authentication steps, providing extra behavioral context beyond annotations.

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, each essential: purpose, return format, auth details. No wasted words.

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?

No output schema, but description fully covers return structure. Simple tool with no parameters; this description suffices.

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?

No parameters in schema; description adds no param info but compensates by explaining output structure. Baseline 4 for zero params.

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?

Clearly states 'List all websites created by the authenticated user.' Verb and resource are specific, and it distinguishes from sibling tools like create_site or search_businesses.

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?

Explicitly mentions authentication requirement and where to generate API key. Does not detail when not to use, but context is sufficient.

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

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

While annotations already indicate readOnlyHint=false and destructiveHint=false, the description adds important behavioral details: it creates a new version, reassembles pages, returns a status field with polling instructions, and enforces serial concurrency on the same businessId. These go beyond what annotations provide.

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 concise and well-structured: first sentence states purpose, second gives usage context, third lists required params, fourth describes the return value, fifth explains polling, sixth enforces concurrency. Every sentence adds value and is front-loaded with the main purpose.

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?

Despite lacking an output schema, the description adequately explains the return format and polling behavior. It also addresses concurrency and the effect on pages. It could mention error handling but overall provides sufficient context for an AI agent to invoke the tool 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?

The input schema has 100% coverage with descriptions for each parameter. The description restates the required parameters but does not add new semantic meaning beyond the schema. Baseline is 3 per guidelines for high coverage.

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 action ('Regenerate the footer'), the target ('of a WebZum site'), and the outcome ('Creates a new version with a fresh AI-generated footer and reassembles every page'). This distinguishes it from siblings like regenerate_header or regenerate_logo.

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 specifies when to use the tool ('Use when the user wants different footer content, layout, or copy'). It does not explicitly state when not to use it, but the context of sibling tools and the concurrency note provide implicit guidance.

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

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

Annotations only state readOnlyHint=false and destructiveHint=false. The description adds crucial context: it creates a new version, reassembles every page, handles async status, and imposes serial concurrency. No contradictions with annotations.

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 concise, well-structured into three sections: what it does, when to use, and async/concurrency details. Every sentence adds value without redundancy.

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, the description explains return format and polling behavior. It covers concurrency constraints and the effect on pages. The sibling list includes other regeneration tools, and the description adequately differentiates this tool.

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 100%. The description lists the required parameters and adds context for pageId ('typically home'), but for businessId and versionId it merely restates the schema. Overall adds moderate extra value beyond schema descriptions.

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 regenerates the header (nav bar, logo placement, top-of-page) and creates a new version with a fresh AI-generated header. It distinguishes itself from sibling tools like regenerate_footer and regenerate_logo by specifying the action on the header.

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 explicitly says 'Use when the user wants the nav restyled, links reordered, or the header redesigned.' It also warns about concurrency: 'edits on the same businessId MUST be serial' and provides guidelines for polling when status is in_progress.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description explains it creates a new AI-generated image, returns status, and requires polling. It adds concurrency and no contradictions.

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?

Every sentence serves a purpose. The description is well-structured, front-loaded with the main action, and includes necessary details without fluff.

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, the description covers the return object structure, polling behavior, and concurrency constraints. It is complete for agent usage.

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 has 100% coverage, so baseline 3. Description adds value by listing required parameters, explaining userMessage with examples, and noting assistantContext accompanies userMessage.

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 regenerates one image inside a specific WebZum section, distinguishing it from sibling tools like regenerate_footer, regenerate_header, and regenerate_logo.

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?

It explicitly says when to use (regenerate one image), provides optional userMessage steering, and crucially states concurrency rule: edits on the same businessId must be serial. It also instructs polling if status is 'in_progress'.

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

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

Discloses return format with status field, polling necessity, concurrency constraint, and that it creates a new version. Adds context beyond annotations (readOnlyHint false, destructiveHint false) by explaining async behavior and serialization requirement.

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?

Compact 6-sentence description that first states purpose, then optional steering, required params, return and polling, and concurrency. No filler.

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?

No output schema, so description explains return shape and status. Provides polling instructions and concurrency rule. Covers all necessary context for an async mutation tool.

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 baseline is 3. Description adds value by providing examples for userMessage and note that pageId is typically 'home'. Does not explain assistantContext, but schema already does.

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?

Clearly states verb 'Regenerate', resource 'logo for a WebZum site', and method 'using AI'. Differentiates from sibling tools like regenerate_footer by specifying 'logo'.

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?

Explicitly describes when to use (regenerate logo), how to steer with userMessage with examples, required parameters, concurrency rule (must be serial per businessId), and polling instructions for async completion.

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

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

Annotations indicate read-only and non-destructive. Description adds authentication requirements (API key), output format (list of candidates with confidence scores), and limits (up to 10 ranked results). No contradiction.

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?

Concise, front-loaded with purpose, well-organized with examples and bullet points. Every sentence adds value.

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?

Covers key aspects: output type, confidence scores, maximum results, and required authentication. Lacks error handling details but sufficient given single parameter and no output schema.

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 covers the single 'query' parameter with a description. Description enhances understanding with examples and acceptable formats. Baseline 3 due to 100% schema coverage, but added value justifies 4.

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?

Description clearly states 'Search for businesses by name, phone number, or location.' It identifies the resource (businesses) and action (search), and differs from siblings that deal with site creation and hosting.

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?

Explicitly says 'Use this to find existing businesses before creating a website.' Provides examples of different query types. Does not exclude alternatives, but context is sufficient.

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

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

Beyond annotations (readOnlyHint: false, destructiveHint: false), the description details the internal process (LLM, HTML diff, reassembly), return value (versionId, status), polling requirement for in_progress status, and concurrency behavior. No contradictions.

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 well-structured with a clear summary sentence, followed by process explanation, examples, required fields, return value, and concurrency notes. Each sentence serves a purpose without redundancy.

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 tool with no output schema, the description covers return value (versionId, status), polling instructions, concurrency constraints, and required inputs. It also references a sibling tool (get_site_status) for follow-up, making it self-contained for correct use.

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% (baseline 3). The description adds value by explaining that conversationHistory must contain verbatim user words (do not paraphrase) and that at least one user turn is required. It also clarifies the role of versionId and businessId beyond 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?

The description clearly states the tool edits a generated WebZum site via natural language descriptions. It distinguishes itself as the primary editor from siblings like regenerate_footer or regenerate_header, and provides concrete examples.

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 explicitly says 'Use this for nearly all edits' and lists examples. It also provides critical concurrency guidance: serial edits on the same businessId and polling via get_site_status. Required parameters are clearly stated.

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