aio-geo

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

Annotations declare readOnlyHint=true, but the description states that setting dryRun false (with an operator key) can enable writes. This directly contradicts the read-only annotation, making the tool's behavioral profile inconsistent and potentially misleading.

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 sentences, front-loaded with purpose and followed by a critical safety constraint. No unnecessary words or repetition.

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?

The description covers the main purpose and dry-run safety, and the schema handles parameter details like blocked IPs. However, the contradiction with readOnlyHint leaves the write behavior ambiguous, undermining completeness.

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. The description adds crucial semantics for dryRun by requiring an operator key to disable dry-run mode, which is not present in the schema, elevating the score.

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's function: 'Generate a structural fix pack for a public domain.' This is a specific verb+resource combination and differentiates it from siblings like audit_url or list_fixes.

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 usage context: public calls are dry-run by default, and writes require setting dryRun false with an operator key. This tells the agent when and how to safely use the tool, though it doesn't explicitly name 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 already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context by disclosing 'No API key required,' the nature of the audit ('structural'), and the output composition (pillar scores, recommendations, brief link, CLI command). It also clarifies it is not an LLM ranking, preventing misuse.

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 two concise sentences, front-loading the main function and outputs, then adding exclusions. 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?

The tool has a modest schema and full annotations; the description covers purpose, output, authentication, and exclusions. The existence of an output schema means return details need not be described, but the description still lists key outputs, making it complete for the agent.

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 clear descriptions of url and domain. The description does not add substantive parameter-level meaning beyond repeating the public URL/domain scope, so it relies on the schema, earning the baseline score of 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?

The description clearly identifies the tool's purpose with the verb 'Run' and resource 'structural AI Search Readiness audit for a public URL or domain.' It also lists the specific outputs (pillar scores, recommendations, brief link, CLI command), which distinguishes it from siblings like rescore_url by stating 'Not an LLM ranking.'

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 context that the tool is for structural audits and explicitly states 'Not an LLM ranking,' which helps differentiate it from scoring tools. However, it does not name alternative sibling tools or give explicit when-to-use vs when-not-to-use guidance beyond this exclusion.

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 the annotations (readOnlyHint, openWorldHint, etc.), the description adds meaningful behavioral assurances: 'Never returns secrets' and 'No API key required.' These are valuable safety and authentication details not present in the 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?

Two concise sentences front-load the core purpose, with every word contributing value. No redundancy or filler, making it highly efficient.

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 simple health-check tool with an empty input schema and an existing output schema, the description is complete. It covers environment/API health, safety (no secrets), and authentication requirements, leaving no significant gaps.

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 tool has zero parameters, so the schema already fully covers parameter semantics. The description adds nothing about parameters, but none are needed. Baseline for no parameters is 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?

The description clearly states 'Return environment and API health' with a specific verb and resource, distinguishing it from sibling tools like apply_fix and audit_url. No ambiguity about what this tool does.

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 provides useful context ('No API key required') but does not explicitly state when to use this tool over alternatives or mention exclusions. The usage context is implied rather than 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, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context: it mentions the return contents (score, top gaps, shareable brief path) and clarifies that no API key is required. It also explicitly states what the tool is not (an LLM ranking). No contradictions with annotations exist.

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 three short, front-loaded sentences. Each sentence adds value: what it returns, what it is not, and a key operational fact (no API key). No word is wasted, and the structure is easy to scan.

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?

The tool has only two parameters, both well-documented in the schema, and an output schema exists (per signals). The description covers the core purpose, output components, and an authentication detail, making it complete for an AI agent to decide and invoke correctly. The output schema covers return-value details, so the description does not need to.

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%, so the schema already documents both parameters (url and domain) including their formats and constraints. The description does not add extra meaning about the parameters themselves, though it uses 'domain' in the text. Baseline of 3 is appropriate given high schema 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 tool returns an executive structural brief for a domain, enumerating the contents (score, top gaps, shareable brief path). The verb 'Return' is specific, and the resource ('a domain') is explicit. The note 'Not an LLM ranking' further differentiates it from potential similar tools.

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 implies when to use (when an executive structural brief is needed) and explicitly states a when-not ('Not an LLM ranking'). It also mentions 'No API key required,' providing context for ease of use. However, it does not explicitly reference sibling tools or provide alternative recommendations beyond that single exclusion.

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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explicitly stating 'No files are written' and 'No API key required,' reinforcing the read-only nature and providing extra context beyond the 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 a single sentence, front-loaded with the primary action and resource. Every word earns its place, and it is highly concise without sacrificing 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 simplicity (2 params, no nested objects) and the presence of an output schema, the description is complete. It covers purpose, read-only behavior, and authentication requirements sufficiently.

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%, and both parameters (url and domain) have detailed descriptions. The tool description adds little beyond the schema, but since the schema is comprehensive, a baseline score of 3 is appropriate.

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 (Return) and the resource (a dry-run structural fix pack for robots, schema, anchors), which distinguishes it from siblings like apply_fix and audit_url. It is specific and unambiguous.

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 dry-run and 'No files are written' wording implies this is for previewing fixes before applying, but it does not explicitly name alternatives or state when not to use it. The usage context is present but not fully elaborated.

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 the annotations (readOnlyHint, idempotentHint, destructiveHint, openWorldHint), the description adds that the audit is 'fresh' and 'public,' explicitly states it is 'Not an LLM ranking,' and notes 'No API key required.' These details enrich the behavioral profile without contradicting the 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 four short, information-dense sentences. It front-loads the core purpose, then adds relational, exclusions, and access prerequisites. Every sentence earns its place with zero 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 the tool's simplicity (two optional alias parameters), full schema coverage, output schema presence, and robust annotations, the description covers the essential context. Minor gaps include lack of explicit timing for when a rescore is needed relative to audit_url, but overall it is complete for effective tool selection.

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 already provides 100% coverage with detailed descriptions for both parameters (url and domain), including the alias relationship and constraint to use only one. The description adds no new parameter-level meaning beyond what the schema states, so the baseline score of 3 is appropriate.

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's function: 'Run a fresh public structural audit (rescore) for a URL or domain.' It uses a specific verb ('run'), defines the resource ('URL or domain'), and distinguishes itself from sibling tools by noting 'Same engine as audit_url' and clarifying 'Not an LLM ranking.' This makes the purpose explicit and unique.

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 useful context: it is a rescore, uses the same engine as audit_url, and requires no API key. This implies when to use it but does not explicitly state 'use this instead of audit_url' or list exclusions. It lacks a clear when-not-to-use statement but offers enough contextual guidance to differentiate from siblings.

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