Ibge Br

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false, covering safety and idempotency. The description adds that it returns time series keyed by period, which is useful but not essential beyond annotations. 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?

Three sentences, no wasted words. The purpose is front-loaded, and key usage guidance is provided succinctly. Each 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?

Despite no output schema, the description states the return format ('time series keyed by period'), and the examples cover typical use cases. For a 4-parameter data query tool with high schema coverage, this is 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?

Schema description coverage is 100%, so the schema already documents each parameter well. The description adds value by giving concrete examples for aggregate (e.g., '1737') and variable (e.g., '63'), and explains the periods format, enhancing the schema's meaning.

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 pulls official IBGE/SIDRA statistical series, specifies the exact parameters needed, and gives concrete examples (IPCA, population). It distinguishes itself from sibling tools like list_aggregates by focusing on data retrieval rather than discovery.

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 to specify aggregate, variable, periods, and locality, and provides common usage examples. It mentions discovering ids via list_aggregates, indicating a prerequisite. However, it does not explicitly state when not to use this tool, leaving some ambiguity.

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 the tool as read-only, idempotent, and non-destructive. The description adds value by explaining the return format (per-model fields + combined view) and the cost implications (free default vs. BYO Anthropic key). 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 two sentences, each serving a distinct purpose: first defines the action and output, second adds pricing and structure details. No redundant information, front-loaded with key 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?

The description covers return values (per-model scores, confidence, etc.) and parameter usage for a 4-param tool without output schema. It lacks details on error handling or edge cases (e.g., unknown entity), but the open-world annotation implies graceful handling. Adequate for the 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% and parameter descriptions are thorough. The description adds only the default model hint, which slightly clarifies but doesn't significantly extend meaning. Baseline 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 specifies a clear action ('Probe one or more LLMs'), resource ('business / brand / product / topic'), and output ('score visibility 0-100 per model'). It distinguishes from siblings by focusing on visibility scoring across models, which is unique among tools like 'scan_competitor_ai_presence'.

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 states use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies when to provide an API key for Anthropic. However, it does not mention when NOT to use or suggest alternative tools, leaving a minor gap.

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, idempotent, and non-destructive behavior. The description adds value by explaining the tool internally routes questions to appropriate sub-tools and returns structured answers with pipeworx:// citation URIs, which is not evident from annotations alone.

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 paragraph that front-loads the key message ('PREFER OVER WEB SEARCH'), then lists supported domains, explains the routing mechanism, and provides examples. It is well-structured and each sentence adds value, though it could be slightly more concise.

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 this is a simple single-parameter tool with no output schema, the description is remarkably complete. It covers purpose, usage, behavior (routing to sub-tools), output format (structured answer with citations), and provides extensive examples. It compensates for the lack of output schema by detailing the return value.

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 fully describes the 'question' parameter with 100% coverage. The description enhances this by explaining that the question will be analyzed and routed to the correct internal tool, adding context about how the parameter is used beyond the schema's description.

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 routes questions to 2,866 tools across 623 verified sources and returns structured answers with stable citation URIs. It distinguishes itself from web search by explicitly saying 'PREFER OVER WEB SEARCH' and from sibling tools by positioning itself as the primary factual query router.

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 guidance: 'PREFER OVER WEB SEARCH' and 'Use whenever the user asks...' with a list of example queries. It covers a wide range of use cases but does not explicitly discuss when not to use the tool or compare it to specific sibling tools beyond the general preference.

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, etc.), the description provides extensive behavioral context: it explains the fan-out process, response shapes (result.market, result.analysis, result.evidence), safety mechanisms (low-confidence short-circuit, closed market skip, illiquidity warning), and status codes. This goes far beyond what annotations alone convey, fully informing the agent of the tool's actions and constraints.

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 relatively long but well-structured with capitalized sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY) that make it easy to scan. Every sentence provides useful information without redundancy. Slight verbosity in fan-out examples could be trimmed, but overall it earns its length.

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 thoroughly explains the response structure and possibilities (market, analysis, evidence). It covers edge cases like low-confidence matches, closed markets, and wide spreads, and provides safety instructions. The agent has enough context to use the tool correctly without additional assumptions.

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, but the tool description adds significant value by providing examples, explaining the depth parameter options ('quick' vs 'thorough' defaults), and detailing the include_raw parameter's impact on response size. This extra context helps the agent choose appropriate parameter values, justifying a score above the baseline 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 states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and provides examples, making it easy to understand what the tool does. The mention of classifiers and fan-out examples further clarifies the scope, distinguishing it from sibling tools like polymarket_edges that focus on specific calculations.

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 recommends using the tool for scenarios like 'should I bet on X' and 'what does the data say about Y'. It also explains safety behaviors (low-confidence resolution, closed markets) that help the agent decide when to use it. However, it does not directly contrast with sibling tools or specify when NOT to use it, though the context implies it's for general research.

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 readOnly, openWorld, idempotent, non-destructive. The description adds data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs) and explains the fix for fiscal year handling, enhancing transparency without 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?

The description is well-structured, beginning with the core purpose, then enumerating per-type behavior, and ending with benefits. Every sentence adds value; no redundant or filler content.

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 explains return format (paired data with citation URIs) and sorting behavior. It covers all necessary invocation details, making the tool self-contained for an AI 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%, and the description adds meaningful context: for 'type' it explains data fetched per type, for 'values' it provides examples (tickers/CIKs, drug names) and constraints (2-5 items).

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 compares 2-5 companies or drugs side by side. It uses a specific verb and resource, and distinguishes itself from siblings by noting it replaces 8-15 sequential lookups.

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 lists when to use: for comparison queries like 'compare X and Y', 'X vs Y', 'which is bigger', or rank-by-metric. Details per entity type and mentions sorted results, providing clear context.

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, so the safety profile is clear. The description adds that the tool returns full schemas and examples, but no additional behavioral traits like rate limits or auth requirements are disclosed.

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 but informative, front-loading purpose and usage. It could be slightly tighter, but each 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?

Given the tool's simplicity (2 parameters, no output schema), the description fully covers what the tool does, when to use it, and what it returns, leaving no 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?

Schema description coverage is 100%, so the input schema already documents both parameters. The description implies the 'limit' parameter by mentioning 'top-N most relevant tools', but adds no new semantics beyond what the schema provides.

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 'Find tools by describing the data or task' and lists specific domains like SEC filings, FDA drugs, etc. It distinguishes from siblings by advising to call this FIRST when many tools are available.

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 context: 'Use when you need to browse, search, look up, or discover what tools exist for' followed by examples. It also suggests calling this FIRST before using other tools, though it does not mention specific 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 readOnlyHint and idempotentHint. The description adds transparency about return fields, known issues (patents sunset, GDELT→GNews fallback), and data freshness (Run 6 fix). 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?

The description is a dense paragraph that front-loads purpose and then details returns and limitations. It could benefit from bullet points for readability, but 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 the tool's complexity and lack of output schema, the description is thorough, covering return fields, limitations, and data sources. However, it does not mention error responses or pagination, which would enhance 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% with good descriptions. The description adds meaning: explains that type is currently only 'company', and value can be ticker or zero-padded CIK. It clarifies that names are not supported, which supplements 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's purpose: 'Get everything about a US public company in one call.' It provides specific user queries that trigger its use and distinguishes itself from alternatives like calling multiple individual 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 explicitly says when to use it (e.g., user asks 'tell me about X') and contrasts with using multiple other tools. It also advises that names are not supported and recommends using resolve_entity first, offering clear guidance on prerequisites.

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 convey destructiveHint, and the description adds context about sensitive data and staleness. No contradiction, and additional context is valuable.

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 sentences, front-loaded with purpose, and every word adds value. Highly concise.

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 tool with one parameter and no output schema, the description is mostly complete. It covers usage and sibling relations, but does not address behavior when key is missing (though idempotentHint implies safety).

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 reinforces the key purpose but adds no additional parameter-specific semantics 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 action 'delete' and the resource 'memory by key', and it distinguishes itself from siblings by naming 'remember' and 'recall'.

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 scenarios for use (stale context, done task, clear sensitive data) and suggests pairing with siblings, but does not specify when not to use.

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 read-only, idempotent, safe. Description adds context: fetches page, extracts title/description/key links, emits standard markdown. 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?

Three sentences, front-loaded with main action, no wasted words. 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?

Despite no output schema, description specifies output format (single text blob for site-root/llms.txt) and mentions standard llms.txt markdown, sufficient for this simple generation 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%, and description merely restates schema info (e.g., url is Full URL, max_links defaults 25 max 50). No additional meaning 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?

Description clearly states the tool generates an llms.txt file for a URL, with specific verb and resource. It differentiates from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than scanning.

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 lists use cases (client indexing, drafting, auditing) and describes the process. However, does not explicitly state when not to use or compare to siblings.

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 readOnlyHint and idempotentHint, so the description doesn't need to restate those. The description adds value by explaining that the tool lists tables grouped by subject and supports optional filtering by acronym. This enriches the agent's understanding of what the tool does 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 remarkably concise: two sentences that convey the tool's purpose, usage, and optional functionality. Every sentence adds value with no redundant or extraneous information. It 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?

Given the low complexity (one optional parameter, no output schema, annotations present), the description is mostly complete. It explains the tool's role in the workflow (discovery for aggregated_data) and its filtering capability. However, it could mention that the output is a list of aggregate tables with IDs and subjects, but this is implied by 'browse the catalog'.

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% for the single parameter 'acronym', which already has a description. The tool description adds further meaning by explaining that the acronym filters by research/subject and providing examples like 'PNAD' and 'IPCA'. This helps the agent understand the parameter's usage 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's purpose: browsing the catalog of IBGE/SIDRA aggregate tables grouped by subject. It specifies the action ('Browse'), the resource ('aggregate tables'), and the purpose ('discover aggregate ids to pass to aggregated_data'). This effectively differentiates it from sibling tools like aggregated_data, which uses the ids.

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 tells when to use this tool: to discover aggregate ids for later use with aggregated_data. It also mentions an optional filter by acronym. While it does not explicitly state when not to use it, the context is clear and the guidance is sufficient for an AI agent to decide.

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 cover read-only, idempotent, etc. Description adds what is returned (7-digit IBGE id and name) without contradicting 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?

One sentence plus example, no unnecessary words. Information is front-loaded.

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 simplicity (1 required param, no output schema, clear annotations), the description fully covers what the tool does and what it returns.

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 100% with description of 'uf' parameter. Description adds an example but does not provide additional semantic details 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?

Clearly states the tool lists municipalities for a given state, provides an example, and distinguishes from sibling tools like list_states and lookup_municipality.

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?

States when to use (for a given state) with example, but does not explicitly mention when not to use or 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by specifying the exact data returned (id, sigla, name, region) and giving a concrete example, which goes 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?

Two sentences with no wasted words. The description is front-loaded with the action and quickly provides useful context and an example.

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 list tool with one optional parameter and no output schema, the description is complete. It explains the purpose, the data returned, and a usage scenario, which is sufficient for an agent to invoke it 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?

Schema description coverage is 100%, so the description need not add param details. The description does not mention the 'orderBy' parameter, but the schema already describes its values and default. Baseline 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 explicitly states it lists all 27 Brazilian states with specific fields (id, sigla, name, region) and provides an example mapping 'SP' to São Paulo, Sudeste. This clearly distinguishes it from sibling tools like list_municipalities.

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 notes it is 'useful for resolving state names/codes before querying municipalities or regional data,' indicating a specific use case. However, it does not explicitly mention when not to use it or name alternative tools, though sibling context implies 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds return value context (hierarchy) but does not mention any additional behavioral traits like rate limits or authorization. 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?

Two sentences with no redundancy. First sentence states purpose and output, second gives a clear example. Efficient and well-structured.

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 single-parameter lookup tool with no output schema, the description fully explains the behavior, identifier format, and response content. No gaps given the tool's simplicity.

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% (parameter 'code' describes 7-digit IBGE code), but the description adds a concrete example and clarifies the output mapping, providing extra meaning 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?

Description clearly states 'look up a single municipality' with specific identifier (7-digit IBGE code) and explicitly mentions return format 'full hierarchy (micro/mesoregion, state, region)'. This distinguishes it from siblings like list_municipalities that likely return multiple results.

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 use when you have a specific IBGE code and need hierarchical details. No explicit when-not-to-use or alternatives, but the example and contrast with siblings (like list_municipalities) provide adequate 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 already indicate read-only, idempotent, non-destructive behavior. The description adds context about the data source (Brazilian census since 1930) and the special 'ranking' mode, enhancing transparency without 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?

Three sentences, front-loaded with the main purpose. Every sentence serves a clear role: stating the function, describing optional filters, and noting the special case. 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 description covers parameters and basic usage but omits details about the output structure, which is important since there is no output schema. The agent lacks information on what the response looks like (e.g., frequency by decade as a list or object).

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%, and the description adds value by explaining the 'ranking' special value for the name parameter and providing examples for locality (e.g., '33' for RJ). This goes beyond the schema documentation.

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 provides Brazilian census name statistics, with specific actions: get frequency for a first name or get top names via 'ranking'. It distinguishes from sibling tools like list_municipalities, which deal with different data.

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 explains when to use the tool (pass a name or 'ranking') and hints at filters (sex, state, decade) with examples. It does not explicitly mention when not to use or alternatives, but this is acceptable as no sibling tool provides similar functionality.

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?

The description discloses rate limits ('5 per identifier per day'), cost ('free'), quota impact ('doesn't count against your tool-call quota'), and how feedback is processed ('team reads digests daily and signal directly affects roadmap'). These details go beyond what annotations provide and are critical for appropriate use.

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 clear sentences, each serving a purpose. It could be slightly more concise but remains efficient and front-loaded with key 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?

Given the tool's simplicity (no output schema, straightforward parameters), the description covers all necessary aspects: purpose, usage triggers, behavioral constraints, and parameter semantics. No gaps are apparent.

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 covers all three parameters with descriptions and enums (100% coverage). The description adds value by emphasizing not to paste the end-user prompt, which clarifies expected message structure. While helpful, this is not essential for schema understanding.

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 purpose: sending feedback to the Pipeworx team about bugs, feature requests, data gaps, or praise. It uses a specific verb ('Tell') and resource ('Pipeworx team'), and distinguishes itself from sibling tools by being the only feedback channel.

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 lists when to use the tool ('when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog', 'when something worked surprisingly well') and provides clear guidance on how to structure the message (describe in terms of Pipeworx tools/packs, avoid pasting end-user prompts).

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, open-world, idempotent, non-destructive behavior. The description adds valuable context: derived from CF analytics engine, no PII, caching duration (5min-1h). 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 lead sentence followed by bullet points. It is informative without being verbose, though the bullet points could be slightly tightened.

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 simple parameter set, sufficient annotations, and explicit mention of return shape ('just (pack, tool, count)'), the description provides complete context for an agent to use the tool effectively.

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 single parameter 'window' has an enum and description in the schema. The description adds meaning by explaining the trade-off: shorter windows surface hot trends, longer show steady-state demand.

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 'top tools, top packs, and total call volume' over a recent window, which is a specific verb+resource. It distinguishes from sibling tools by focusing on what other AI agents are using, rather than listing all tools or entities.

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 lists three use cases: discovering hot data sources, confirming canonical choice, and seeing alignment with agent needs. While it doesn't specify when not to use or alternatives, the context is clear enough for selection.

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 idempotentHint=true. The description adds rich internal details: monotonicity checks, partition-sum validation with a 3pp threshold, Jaccard similarity filtering, and placeholder handling. There is no contradiction with annotations, and the description significantly enhances transparency.

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 verbose and contains detailed algorithmic steps (e.g., Jaccard threshold, placeholder fraction). While informative, it could be more concise by omitting minor implementation details. The structure is clear with mode breakdown, but length slightly detracts.

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 complexity of the tool and no output schema, the description comprehensively covers return values (opportunities array with gap_pp, suggested_trade, reasoning, partition_check) and edge cases. All key aspects are explained, making it self-sufficient for correct invocation.

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% with each parameter described. The description adds value by explaining that 'event' accepts slug or full URL and that 'topic' triggers cross-event search with comparator logic. This enriches the schema information without redundancy.

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 specifies the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It clearly distinguishes two modes (event and topic), and unlike siblings like polymarket_edges or polymarket_kalshi_spread, this tool focuses on cross-market arbitrage detection.

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 explains when to use each mode: 'event' for a single event slug and 'topic' for cross-event searches. It also notes that cross-event mode catches patterns single-event misses, providing context but not explicit when-not-to-use scenarios. Overall, it offers sufficient 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 already indicate safe read-only operation, but description adds caching behavior (cached 1h at KV level keyed on all knobs), exclusion of fed_rate bets from ranking, and detailed explanation of how segments and knobs affect results. 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?

Long but efficient: front-loads purpose, then groups details by segment and knobs. Every section adds necessary context. Minor redundancy (e.g., knobs repeated later), but overall well-structured.

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?

Very complete for a complex tool: explains three model families, caching, exclusions, all 9 parameters, and what opportunities carry (edge_pp_net, kelly_fraction, etc.). No output schema, but return fields are described in text. Covers all aspects an agent needs.

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% description coverage for 9 parameters, but description adds narrative context: explains how min_liquidity, max_spread_pp act as tradeable-edge filters, and clarifies min_partition_leg_kelly's role for partition overround. Adds value beyond 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?

Description specifies verb 'scan', resource 'top Polymarket markets', and outcome 'return opportunities where Pipeworx data disagrees with market price'. Clearly distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement and unique segment types.

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 'Built for "what should I bet on today"' and mentions agents can discover without paging. Notes fed_rate bets are excluded from ranking due to unreliable signal. Lacks explicit when-not-to-use vs alternatives, but provides clear context on tradeable-edge knobs.

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, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds that it returns prices and spreads in 0-1 and percentage points. No extra behavioral traits (rate limits, auth) are needed given 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 front-loaded with purpose and modes, but the second paragraph could be slightly more concise. Still, it's well-structured and every sentence contributes 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?

Given the tool's complexity (2 modes, 3 params, no output schema), the description covers return format and usage context. It lacks some details like precise spread calculation, but is sufficient for an agent to understand what to expect.

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 describes each parameter. The description adds meaning by explaining the two modes and how parameters override each other, providing context beyond the schema's basic 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 defines the tool as a cross-venue spread calculator between Kalshi and Polymarket, with two distinct modes (topic shortcuts and explicit ticker pairs). It distinguishes itself from siblings like polymarket_arbitrage by focusing on inter-venue arbitrage.

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 explains when to use each mode (pre-mapped topics vs. explicit tickers) and the rationale (real arbitrage signal). However, it does not explicitly state when not to use this tool or compare it to alternatives like compare_entities.

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?

Disclosures beyond annotations: scoped to identifier, pairing with remember/forget. Annotations already indicate read-only and idempotent, description adds value with scoping and pairing context.

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, no wasted words. Purpose stated first, followed by usage context and scoping. Efficient and well-structured.

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 key-value retrieval with no output schema, the description covers functionality (get by key, list all), scoping, and pairing with siblings. Completely adequate for agent understanding.

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 on one parameter. Description adds meaning that omitting key lists all keys, which is not in schema description. Provides examples showing both use cases.

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 it retrieves a value saved via remember or lists all keys when omitted. Distinguishes from siblings like remember and forget, and specifies the context of previously stored data.

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 guidance on when to use (look up context stored earlier) and implies not for other purposes. Mentions scoping to identifier, but does not explicitly list alternative tools for other use cases.

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 a safe, read-only, idempotent operation. The description adds valuable behavioral details: parallel fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and output structure (grouped changes, total count, citation URIs). 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 a single paragraph but efficiently packs a lot of information. It is front-loaded with purpose and examples. While slightly lengthy, every sentence adds value. Minor improvement could be structuring into bullet points for clarity, but overall it is effective.

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 (multiple sources, parallel execution, fallback logic) and no output schema, the description covers essential aspects: input parameters, behavior, output structure, and comparisons. It could mention error handling or all-source failure scenarios, but it is largely complete for an AI 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?

While schema coverage is 100%, the description enriches parameters with examples ('since' for ISO dates and relative shorthands like '7d', '30d'), default suggestions ('Use 30d or 1m'), and clarifications ('value' can be ticker or CIK). This goes beyond the schema's base 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's purpose: retrieving recent changes for a company over a specified period. It uses specific verbs ('What's new') and resource ('company'), and provides example queries. It distinguishes itself from the sibling tool 'entity_profile' by explicitly contrasting use cases.

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 guidance on when to use the tool ('what's happening with X') and when to use an alternative ('Use entity_profile instead for static profile'). It also describes the tool's multi-source fan-out logic and fallback behavior, aiding correct invocation.

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 idempotentHint true and destructiveHint false. Description adds persistence details (authenticated vs anonymous) without contradicting 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?

Single paragraph, no wasted words. Front-loaded with purpose. Could be slightly more structured but impactful.

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 key-value store with no output schema and 2 params, description covers purpose, usage, persistence, and pairing. 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?

Schema covers both parameters with descriptions (key and value). Description reinforces but does not significantly add beyond schema. Baseline 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?

Description specifies the tool's function (save data for reuse), provides concrete examples (resolved ticker, target address), and distinguishes from siblings (recall, forget) by mentioning them.

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 (discover something worth carrying forward) and how to pair with recall and forget. Also notes scoping by identifier and session duration.

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, open-world, idempotent, and non-destructive behavior. The description adds that each call cascades through multiple endpoints internally, revealing compound nature and efficiency gain, which goes 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?

Two sentences plus a bullet-like list of supported types. Front-loaded with primary purpose; every sentence contributes meaningful information 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?

Completely covers the two supported entity types with input and output details. Mentions internal cascading and citation URIs, which compensates for lack of output schema. Could mention error handling or rate limits, but given tool simplicity, it is quite 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?

Schema has 100% coverage with descriptions for both parameters. The description adds substantial semantic value: for company type, input can be ticker, CIK, or name with auto-disambiguation; for drug, input is brand or generic name. It also explains return values (e.g., ticker + CIK for company, RxCUI + ingredient for drug).

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 the tool resolves user-spoken names to canonical identifiers, with specific verb 'resolve' and resource 'names to identifiers.' Supported types and their outputs are detailed, and the tool's role is distinct from siblings like entity_profile or compare_entities.

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 advises 'Use FIRST when you have a name but need an ID,' providing clear usage context. It also notes that the tool replaces manual lookups, but does not explicitly contrast with alternatives beyond that.

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, idempotent, non-destructive behavior. The description adds valuable behavioral context: it 'Probes each entity with ai_visibility_check', treats the first entity as the subject, and details return fields (score, confidence, signal density). 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?

Three concise sentences with the core action front-loaded. Every sentence adds value: action, method, use case, and output description. No redundant or unnecessary wording.

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 adequately covers return format ('ranked list with score, confidence, signal density per entity') and behavior (treats first as subject, probes each with ai_visibility_check). Given the tool's moderate complexity and rich annotations, no additional information is needed.

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 4 parameters have schema descriptions (100% coverage). The description adds meaning beyond schema: it clarifies that 'entities' must be 2-8 with first as subject, 'models' default to workers-ai, '_apiKey' only needed for anthropic, and 'context' disambiguates common names. This reduces ambiguity for the AI agent.

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 purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies a specific verb ('compare'), a clear resource ('AI visibility'), and scope ('multiple entities'), strongly distinguishing it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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 usage context: 'Useful for competitive AI-marketing audits' and gives a concrete example ('does Claude know about us as well as our competitors?'). However, it does not explicitly mention when not to use or suggest alternative tools, though the sibling context makes that inferable.

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 significant context: data source (SEC EDGAR + XBRL), return types (verdict with multiple possible values, structured form, actual value with citation, percent delta), and performance benefit (replaces 4–6 sequential calls). 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 concise: one paragraph of about 5 sentences, front-loading purpose and usage, then providing behavioral details. Every sentence contributes 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 fully explains return values (verdict, structured form, actual value, citation, percent delta) and scope limitations (v1 supports company-financial claims). This is complete for a single-parameter 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% for the single parameter 'claim', and its description in the schema includes examples. The overall tool description adds some extra examples and context about supported claim types, but the schema already provides adequate meaning. Baseline 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 uses strong verbs like 'fact-check', 'verify', 'validate', and clearly identifies the resource as 'natural-language factual claim or statement against authoritative sources'. It distinguishes from siblings by focusing on claim verification, which none of the sibling tools directly address. Examples and return types are provided.

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 when to use ('when an agent needs to check whether something a user said is true') and provides example queries. It does not explicitly state when not to use or mention alternatives, but the context is clear enough given the sibling list and the tool's scope.

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