dogceo

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds details about free vs. paid probing, API key handling, and return structure (per-model {score, confidence, signals, raw_response} + combined view). It doesn't contradict 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?

Five sentences front-load the core action, then explain models, return structure, and use cases. No redundant information; 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?

Despite no output schema, the description details the return structure. All four parameters are explained thoroughly. Use cases and model selection are covered, making the tool fully operational for an 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%, but the description adds significant meaning: explains _apiKey usage, context for disambiguation, and models options beyond schema descriptions. This enhances agent understanding of how and when to provide each parameter.

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 probes LLMs for knowledge about an entity and scores visibility, with specific examples (business, brand, product, topic) and use cases (AI-marketing audits, pre-launch brand checks). It distinguishes itself from siblings like ask_pipeworx and entity_profile by focusing on multi-model visibility scoring.

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 explicit use cases and explains when to use the default Workers AI vs. Anthropic (with BYO key). It doesn't explicitly contrast with alternatives, but the context signals list siblings, and the description gives practical guidance on model selection and API key requirements.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains key behaviors: Pipeworx picks the tool and fills arguments automatically, and it returns results from data sources. However, it lacks details on error handling, rate limits, authentication needs, or response formats. For a tool with no annotation coverage, this leaves significant gaps in understanding operational 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 front-loaded with the core functionality, uses efficient sentences, and includes examples that directly support understanding without redundancy. Every sentence contributes to clarifying the tool's purpose and usage, with no wasted words or unnecessary elaboration.

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 (natural language processing with automatic tool selection) and lack of annotations and output schema, the description is incomplete. It explains the high-level process but omits details on response structure, error cases, limitations, or how 'best available data source' is determined. For a tool with no structured output documentation, more behavioral context would be 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?

The schema description coverage is 100%, so the baseline is 3. The description adds value by providing context: it specifies that the question should be in 'plain English' or 'natural language', and the examples illustrate the expected format and scope of queries. This enhances understanding beyond the schema's basic parameter 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's purpose with specific verbs ('ask a question', 'get an answer') and resources ('best available data source'), distinguishing it from sibling tools like list_breeds or random_image by emphasizing natural language querying rather than specific API operations. It explicitly mentions Pipeworx handles tool selection and argument filling, which differentiates it from tools requiring manual parameter specification.

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 this tool ('No need to browse tools or learn schemas — just describe what you need') and includes concrete examples that illustrate appropriate use cases. It implicitly suggests alternatives (e.g., using specific tools like list_breeds for structured queries) by positioning itself as a simplified interface for natural language questions.

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, open-world, non-destructive. Description adds: resolves market, classifies bet type, fans out to right packs (e.g., crypto+fred+gdelt for BTC), returns evidence packet with comparison. Rich 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?

Length is appropriate for a complex tool. Front-loaded with purpose. Every sentence provides value, though some marketing language (e.g., 'core demo product') could be trimmed without loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and complex behavior (multiple input types, variable fan-out), the description fully explains what happens. No gaps: covers resolution, classification, pack selection, and output.

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%: both parameters have descriptions. The description explains market can be slug, URL, or text, and depth defaults to thorough. Adds some context but baseline is 3 since schema already covers param 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 researches Polymarket bets by pulling Pipeworx data, and specifies input types (slug, URL, question text) and output (evidence packet, market-vs-model comparison). It distinguishes from siblings by calling itself the core demo product and claiming better conversion.

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: 'should I bet on X?', 'what does the data say?', 'is there edge?'. Does not explicitly state when not to use or alternatives, but context suggests alternatives like ask_pipeworx exist. Clear context but no exclusions.

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?

No annotations are provided, so the description carries the full burden. It mentions 'random' and 'multiple' images, but lacks details on permissions, rate limits, response format, or potential errors. For a tool with no annotations, this is insufficient behavioral disclosure.

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, efficient sentence with zero waste. It front-loads the core purpose and includes essential context (randomness, breed specificity), making it appropriately sized 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?

Given no annotations, no output schema, and simple parameters, the description covers the basic purpose but lacks details on behavior, output format, or error handling. It is minimally adequate but has clear gaps in completeness for a tool with no structured support.

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 fully documents both parameters. The description adds no additional parameter meaning beyond what the schema provides, such as format examples or constraints, meeting the baseline for 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 specific action ('Get multiple random dog images') and target resource ('for a specific breed'), distinguishing it from siblings like 'random_breed_image' (single image) and 'random_image' (no breed specification). It uses precise verbs and scope.

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 usage context (when you need multiple images of a specific breed) and references 'list_breeds' for valid breed values, but does not explicitly state when to use alternatives like 'random_breed_image' or 'random_image' or any exclusions.

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?

No annotations provided, so description carries full burden. It discloses data sources (SEC EDGAR), output types (paired data, resource URIs), and the fields returned for each entity type. However, it does not mention error handling, rate limits, or whether the tool is read-only, which is implicitly clear but not explicit.

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 purpose. Every sentence provides essential 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?

Return data is described for each type, and resource URIs are mentioned. No output schema, so description compensates. Lacks info on error handling or edge cases, but for the complexity level, it is fairly 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?

Input schema covers 100% of parameters with descriptions. The description adds value by explaining what data is returned per type, indirectly aiding parameter selection (e.g., knowing that 'type' determines the fields). While schema is sufficient, the description enhances 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?

Clearly states the tool compares 2-5 entities side by side, specifies two entity types (company and drug) with distinct data returned, and highlights efficiency (replaces 8-15 sequential calls). Distinguishes itself from sibling tools by its specific functionality.

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 context on when to use (comparison scenarios) and efficiency benefit, but does not explicitly state when not to use or name alternative tools for similar tasks. Sibling tools are distinct, so no direct conflict.

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?

No annotations are provided, so the description carries the full burden. It mentions the tool returns 'the most relevant tools,' implying a ranking or relevance-based search, but does not disclose behavioral traits like rate limits, error handling, or authentication needs. The description adds some context about when to use it but lacks details on operational behavior.

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 appropriately sized and front-loaded, with two sentences that efficiently convey purpose and usage guidelines without unnecessary details. Every sentence earns its place by providing essential information for the 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 the tool's complexity (search functionality with 2 parameters) and lack of annotations or output schema, the description is fairly complete. It explains the purpose, usage context, and output format ('Returns the most relevant tools with names and descriptions'), but could benefit from more behavioral details like search algorithm hints or error cases.

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 both parameters ('query' and 'limit'). The description does not add meaning beyond what the schema provides, such as explaining how the query is processed or the impact of the limit. Baseline 3 is appropriate as the schema handles the heavy lifting.

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 with specific verbs ('Search the Pipeworx tool catalog') and resources ('tool catalog'), and distinguishes it from sibling tools by explaining its unique role in discovering tools among many available options. It explicitly mentions 'Returns the most relevant tools with names and descriptions,' which adds clarity about the output.

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 this tool: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This includes a clear condition (500+ tools) and a recommended sequence (first), helping the agent decide when to invoke it versus 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?

No annotations provided, so description carries full burden. It discloses that the tool returns pipeworx:// citation URIs and replaces 10-15 sequential calls, implying read-only behavior. Could mention error conditions or rate limits, but overall adequate.

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 concise with no fluff. Uses bullet-like enumeration within a single paragraph, front-loading the key benefit (full profile in one call). 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?

Given the complexity of bundling multiple sources and no output schema, the description lists specific data included and mentions citation URIs. It could mention result size or limits, but overall sufficiently complete for a data retrieval 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%, baseline 3. Description adds value beyond schema: clarifies 'type' only supports 'company' (others coming soon), and for 'value' explains ticker/CIK and explicitly states names not supported, referencing resolve_entity.

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 it provides a full profile of an entity across multiple packs in one call, with specific data types listed (SEC filings, revenue, patents, news, LEI). It distinguishes from siblings like resolve_entity (name resolution) and usa_recipient_profile (federal contracts).

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 tells when to use this tool (for comprehensive entity profile) and when not (for federal contracts, use usa_recipient_profile). Also advises using resolve_entity if only a name is available, providing clear 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a deletion operation, which implies mutation/destruction, but doesn't specify whether deletions are permanent, reversible, require specific permissions, or have side effects. For a destructive tool with zero annotation coverage, this leaves significant behavioral questions unanswered.

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, efficient sentence that communicates the core action without any wasted words. It's appropriately sized for a simple tool with one parameter and gets straight to the point.

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 destructive tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after deletion (success confirmation, error responses), whether deletions affect other data, or what constitutes a valid 'stored memory' context. The minimal description leaves too many contextual gaps for a mutation operation.

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 schema description coverage is 100%, with the single parameter 'key' fully documented in the schema as 'Memory key to delete'. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate when the schema does the heavy lifting.

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 target ('a stored memory by key'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'recall' or 'remember', but the verb 'Delete' strongly implies a destructive operation that distinguishes it from read operations.

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 no guidance on when to use this tool versus alternatives like 'recall' (which likely retrieves memories) or 'remember' (which likely creates them). There's no mention of prerequisites, error conditions, or typical use cases beyond the basic action.

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 safety and idempotence guarantees. The description adds value by detailing the internal steps (fetches page, extracts title/description/links, emits standard markdown) and the output format, which aligns with and supplements 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, well-structured paragraph that front-loads the core action, then explains process, output, and use cases. Every sentence adds value with no superfluous 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?

For a simple tool with 2 parameters and no output schema, the description fully covers the tool's purpose, behavior, output (single text blob in standard format), and use cases. An agent can confidently decide to invoke this tool based on the description alone.

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 baseline is 3. The description does not add new meaning beyond what the schema already provides for 'url' and 'max_links' (default and max are already in schema). It repeats the information without additional context.

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 generates a production-ready llms.txt file, using specific verb and resource. However, it does not explicitly distinguish from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which can also relate to AI indexing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear use cases for when to use the tool (e.g., getting a site indexed by AI, drafting llms.txt), offering good context. It does not, however, specify when not to use it or name alternative tools, which would solidify its place among 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the action but doesn't mention any traits like response format, pagination, rate limits, or authentication needs. For a tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves.

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, efficient sentence that directly states the tool's purpose without any wasted words. It is front-loaded and appropriately sized for a simple tool with no parameters.

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 (0 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose but lacks details on behavioral aspects like return format or usage context, which are needed for full understanding despite the low 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?

The tool has 0 parameters, and schema description coverage is 100%, so there's no need for parameter details in the description. The baseline for this case is 4, as the description appropriately avoids redundant information about non-existent parameters.

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 resource ('all dog breeds and their sub-breeds'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'breed_images' or 'random_breed_image', which focus on images rather than breed listings, so it doesn't reach the highest score.

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 no guidance on when to use this tool versus alternatives like 'random_breed_image' or 'breed_images'. It lacks explicit context, prerequisites, or exclusions, leaving usage decisions to inference based on tool names alone.

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?

No annotations provided, so description carries full burden. It discloses rate limit, free usage, and content restrictions. Could mention if feedback is logged or replied to, but current content is sufficient for a feedback tool.

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 covering purpose, usage, rate limit, and restrictions. 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?

Given no annotations or output schema, description covers essential aspects: purpose, usage guidance, rate limit, and content constraints. Could mention expected response (e.g., success acknowledgment), but otherwise 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 coverage is 100% with descriptions for all parameters. The description adds value by guiding users on message content and not repeating prompt verbatim, enhancing semantic understanding 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 is for sending feedback to the Pipeworx team, listing specific use cases (bug reports, feature requests, missing data, praise). This distinguishes it from sibling tools like ask_pipeworx or discover_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?

Explicit instructions on when to use (for feedback) and what to include (describe attempts in terms of Pipeworx tools/data, avoid verbatim prompts). Also mentions rate limit (5 per day per identifier), setting clear expectations.

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, idempotentHint, destructiveHint. Description adds caching details (5min-1h), data source (CF analytics-engine), and privacy note (no PII), which are valuable beyond structured 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?

Four sentences, no redundancy. Front-loaded with purpose, then use cases, then technical details. 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?

For a simple tool with one optional parameter, no output schema, the description covers purpose, usage, caching, data source, and privacy. Does not detail exact return format but specifies content (top tools, packs, volume) adequately.

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 one enum parameter. Description adds semantic guidance: 'shorter windows surface what's hot right now; longer windows show steady-state demand' and notes default value, improving agent understanding beyond enum values.

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 returns trending tools, packs, and call volume. Uses specific verb 'returns' and distinguishes resource ('top tools, top packs, total call volume') from siblings like 'discover_tools' or 'ask_pipeworx'.

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 three explicit use cases and mentions caching behavior. Does not explicitly state when not to use it, but context is clear enough for an 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 indicate readOnlyHint=true and openWorldHint=true, and the description adds behavioral details: it walks child markets, searches across events, groups related markets, checks monotonicity, and returns ranked opportunities with reasoning. No contradictions with annotations. Minor gap: does not mention data staleness or rate limits, but overall transparent.

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 introductory sentence followed by two detailed paragraphs for each mode. Every sentence adds value, and the information is front-loaded. 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?

Given the tool's complexity (two modes, cross-event search), the description covers purpose, modes, parameters, and output structure. No output schema exists, but the description mentions returned format (ranked opportunities with reasoning). Minor omission: error handling or edge cases (e.g., no opportunities found).

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 significant meaning beyond the schema by explaining how each parameter is used (e.g., 'walks that event's child markets' for event, 'searches across separate events' for topic) with concrete examples, raising 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 clearly states the tool finds arbitrage opportunities on Polymarket by checking monotonicity violations. It details two distinct modes ('event' and 'topic') with concrete examples, and distinguishes itself from siblings like 'polymarket_edges' by focusing on cross-market pricing inconsistencies.

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 each mode, including a scenario where cross-event mode is necessary (e.g., multiple events with different deadlines). It explains the limitation of single-event mode and why topic mode exists, giving agents clear context 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?

The description goes beyond annotations by detailing the model (V1 crypto-price bets, lognormal from FRED, coinpaprika prices), the process (scans top markets, groups by asset, fetches price history once, computes probability, ranks by |edge|), and output (top N with suggested trade direction). Annotations already indicate readOnlyHint=true, but the description adds rich behavioral 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?

The description is informative but slightly verbose, especially the model explanation in the middle. It is front-loaded with the main purpose, but the technical details could be streamlined for quicker parsing. Still, every sentence provides 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 complexity of the tool and no output schema, the description explains the return structure (ranked edges with trade direction) and the methodology. It lacks explicit mention of error handling or limitations, but is sufficiently complete for its purpose.

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 for each parameter (limit, window, min_edge_pp). The description adds little beyond these; it mentions 'returns top N' which correlates with limit, but does not enhance schema semantics. 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 clearly states the tool's purpose: scanning Polymarket markets and returning those with largest discrepancies between Pipeworx model probability and market price. It explains the model and output, and the verb 'scan...and return' is specific. While it doesn't explicitly differentiate from siblings like 'polymarket_arbitrage', the unique focus on edge detection is evident.

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 'Built for the 'what should I bet on today' question', providing a clear use case. It implies when to use (opportunity discovery) but doesn't explicitly state when not to use or compare with sibling tools like 'polymarket_arbitrage'. This is 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds further behavioral context: explains the spread source (different participant pools), return format (leg-by-leg prices, spread in percentage points), and mode details. 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 informative and well-structured with clear sections for modes and output. It is slightly verbose but front-loads the key purpose efficiently. Every sentence adds value, though could be trimmed slightly.

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 the return values (leg-by-leg prices, spread percentage). All three parameters are covered, and the two modes are thoroughly described. The tool is relatively simple with optional parameters, so the description 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 coverage is 100% with descriptions for each parameter. The description adds value by explaining how parameters interact (e.g., 'overrides the topic-mapped Kalshi side'), providing meaning beyond schema. Slight improvement beyond 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?

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes from siblings by focusing on two venues and explicitly mentioning the spread calculation, unlike polymarket_arbitrage which likely involves different venues.

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 two modes (topic vs explicit parameters) and when to use each, providing clear context. However, it does not explicitly state when not to use this tool compared to siblings like polymarket_arbitrage, 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?

No annotations are provided, so the description carries full burden. It discloses the tool's core behavior (returns a single random image), but lacks details like rate limits, error handling, image format, or whether it's a read-only operation. The description doesn't contradict annotations (none 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 a single, efficient sentence with zero wasted words. It's appropriately sized for a simple tool and front-loads the key information (action, resource, scope).

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 low complexity (1 parameter, no annotations, no output schema), the description is minimally complete. It explains what the tool does but lacks details on output format or behavioral constraints. Without an output schema, the description should ideally mention what's returned (e.g., image URL or data).

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 the schema fully documenting the 'breed' parameter. The description adds no additional parameter information beyond what the schema provides, so it meets the baseline of 3 for high schema coverage without compensating value.

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 specific action ('Get'), resource ('single random dog image'), and scope ('for a specific breed'). It distinguishes from sibling tools: 'breed_images' likely returns multiple images, 'list_breeds' lists breeds, and 'random_image' might be for random images without breed specification.

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 usage context (when you need a random image for a specific breed), and the schema references 'list_breeds' for valid values, providing some guidance. However, it doesn't explicitly state when NOT to use this tool or name alternatives like 'breed_images' or 'random_image'.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool returns a 'random dog image URL', but does not describe key behaviors such as rate limits, error handling, or whether the URL is temporary or permanent. For a tool with zero annotation coverage, this leaves significant gaps in understanding its operational traits.

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, efficient sentence that front-loads the core purpose ('Get a random dog image URL') and adds necessary context ('from any breed'). There is no wasted wording, and every part earns its place by clarifying scope and resource.

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 (0 parameters, no annotations, no output schema), the description is adequate but has clear gaps. It explains what the tool does but lacks details on output format (e.g., URL structure, image metadata) and behavioral aspects like reliability or limitations, which are important for a tool with no structured data to rely on.

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 0 parameters, and schema description coverage is 100%, so the schema already fully documents the lack of inputs. The description adds no parameter-specific information, which is appropriate here. Baseline is 4 for zero parameters, as no compensation is needed.

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 specific action ('Get'), resource ('random dog image URL'), and scope ('from any breed'), distinguishing it from sibling tools like 'breed_images' (which likely requires a breed parameter) and 'random_breed_image' (which might involve breed-specific randomness). It avoids tautology by not just repeating the name 'random_image'.

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 usage context by specifying 'from any breed', suggesting this tool is for random images without breed restrictions. However, it does not explicitly state when to use this versus alternatives like 'random_breed_image' (which might be for breed-specific random images) or 'list_breeds' (for listing breeds), 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?

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: retrieving or listing memories, persistence across sessions, and the optional key parameter. However, it lacks details on error handling (e.g., if key doesn't exist), return format, or performance aspects like rate limits, leaving some gaps in behavioral 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?

The description is front-loaded and concise, with two sentences that efficiently convey purpose, usage, and context. Every sentence earns its place: the first defines the tool's actions and parameter logic, and the second provides application context 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 moderate complexity (1 optional parameter, no output schema, no annotations), the description is mostly complete. It covers purpose, usage, and parameter semantics well. However, it lacks details on output format or error cases, which could be helpful for an agent, slightly reducing 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?

The schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the semantics of omitting the key ('omit to list all keys'), which clarifies the dual functionality beyond the schema's technical definition. This enhances understanding of parameter usage, justifying a 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 clearly states the tool's purpose with specific verbs ('retrieve', 'list') and resources ('previously stored memory', 'all stored memories'), distinguishing it from siblings like 'remember' (store) and 'forget' (delete). It explicitly mentions retrieving context saved earlier in the session or previous sessions, making the scope 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 description provides explicit guidance on when to use this tool vs. alternatives: 'Retrieve a previously stored memory by key, or list all stored memories (omit key).' It specifies the condition for listing (omitting key) and contrasts with siblings like 'remember' for saving and 'forget' for deletion, offering clear usage 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?

With no annotations, description carries full burden. Discloses fan-out behavior to SEC, GDELT, USPTO, return structure, and 'since' format. Could explicitly state readonly nature, but implied.

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?

Packed with useful info, front-loaded with purpose. Slightly long but every sentence adds value. Could tighten by removing filler words, but 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?

Comprehensive for a 3-param tool with no output schema. Explains return values, parameter details, and branching behavior. No obvious 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?

Adds significant meaning beyond schema: explains 'since' formats (ISO, relative), 'type' limitations, and 'value' examples (ticker or CIK). Schema coverage is 100%, but description enriches 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?

Clearly states verb+resource: 'What's new about an entity since a given point in time.' Distinguishes from siblings like entity_profile by focusing on changes over time. Provides specific detail for type='company'.

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?

Explicit usage scenarios: 'brief me on what happened with X' or change-monitoring workflows. Lacks explicit when-not-to-use or alternatives, but context is clear enough.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the tool stores data, specifies persistence characteristics (authenticated users get persistent memory, anonymous sessions last 24 hours), and implies this is a write operation. However, it doesn't mention potential limitations like storage capacity or rate limits.

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 perfectly front-loaded with the core purpose in the first sentence, followed by usage guidance and behavioral details. Every sentence earns its place with no wasted words, making it highly efficient while remaining informative.

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 write operation tool with no annotations and no output schema, the description provides good context about persistence behavior and usage scenarios. It could be more complete by mentioning what happens on storage failure or if the key already exists, but it covers the essential aspects well given the 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?

With 100% schema description coverage, the schema already documents both parameters thoroughly. The description doesn't add significant semantic information beyond what's in the schema properties, though it reinforces the purpose of storing 'intermediate findings, user preferences, or context' which aligns with the parameter 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 with specific verbs ('store a key-value pair') and resource ('in your session memory'), distinguishing it from sibling tools like 'recall' (retrieve) and 'forget' (delete). It explicitly identifies what gets stored and where.

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 this tool ('to save intermediate findings, user preferences, or context across tool calls') and distinguishes it from alternatives by specifying the storage mechanism. It also clarifies the persistence differences between authenticated and anonymous sessions.

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?

With no annotations, the description carries full burden. It explains the tool returns ticker, CIK, company name, and pipeworx:// URIs, and that it is a single call. It implies read-only, stateless behavior, which is appropriate for a resolution tool. No mention of permissions or error handling, but sufficient for safe invocation.

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 extremely concise: two sentences and a few additional details. It front-loads the core purpose and immediately provides version, example inputs, return values, and a clear benefit. Every sentence adds value without waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description covers return fields (ticker, CIK, name, URIs) and version limitation. It is complete for a straightforward lookup tool, though it could optionally mention error behavior (e.g., if entity not found).

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%, but description adds valuable context beyond schema: examples of ticker ('AAPL'), CIK ('0000320193'), and company name ('Apple'), and clarifies the 'type' parameter is currently limited to 'company'. This helps the agent understand input formats.

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 resolves an entity to canonical IDs across Pipeworx data sources in a single call, with specific verb ('Resolve') and resource ('entity to canonical IDs'). It distinguishes from siblings by noting it replaces 2-3 lookup calls, implying efficiency over alternatives like ask_pipeworx.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use (e.g., needing canonical IDs for a company) and gives examples of accepted inputs. It indicates version restriction (v1 only 'company'), but does not explicitly state when not to use or name alternative tools.

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 declare readOnlyHint, idempotentHint, openWorldHint, non-destructive. Description adds process details (probing each entity, ranking, output with score/confidence/signal density) beyond annotations, providing a clear behavioral model.

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, front-loaded with main purpose, then details. No wasted sentences. Could be slightly more structured (e.g., bullet points for output), but effective and 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?

No output schema, but description explains output format (ranked list with score, confidence, signal density). Covers input and behavior. No obvious gaps for a competitive audit 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% description coverage, but description adds meaning: entities are brand names, first is subject, models and _apiKey conditions explained. Adds context not in schema (e.g., 'free default', 'passed to api.anthropic.com').

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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check for each entity and ranking results. Distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities by specifying the competitive audit use case.

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 suggests a use case: competitive AI-marketing audits. Implicitly contrasts with ai_visibility_check for single entity. Lacks explicit when-not-to-use or alternative tool names, 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?

With no annotations, the description carries the full burden. It discloses return types (verdict, extracted form, actual value with citation, percent delta) and the integration of multiple steps (NL parsing to comparison). It lacks details on error handling, data freshness, or prerequisites like internet access.

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 with no fluff. The first sentence states the core function and scope; the second details outputs and efficiency gains. Every sentence is informative 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?

Given no output schema, the description adequately explains return values and supported claim types. It does not mention limitations, failure modes, or data source constraints, which would improve completeness for a complex 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%, providing parameter descriptions. The description adds value with concrete examples (e.g., 'Apple's FY2024 revenue was $400 billion'), clarifying 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: fact-check natural-language claims against authoritative sources. It specifies the domain (company-financial claims for public US companies) and distinguishes itself by noting it replaces 4-6 sequential agent calls, making its role distinct from siblings.

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 limits usage to 'company-financial claims (revenue / net income / cash for public US companies),' providing clear context. However, it does not explicitly state when not to use the tool or mention alternative tools, leaving some ambiguity.

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