science

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

The description adds behavioral details beyond annotations: it specifies that probing is free for the default model, requires user's API key for Anthropic, and passes the key directly to Anthropic's API. No contradictions with annotations (readOnly, openWorld, idempotent, non-destructive).

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, front-loading the main purpose and return format. It uses efficient language without unnecessary detail.

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

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

The description covers the return format (per-model details and combined view), input parameters, and typical use cases. With no output schema, this provides sufficient context for an agent to understand the tool's 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% and the description adds minor value by explaining the default model and the optional nature of models and _apiKey. However, it does not significantly enhance 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's purpose: probing LLMs for brand visibility and scoring (0-100). It specifies the default model and optional Anthropic probing, distinguishing it from sibling 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 mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains that the Anthropic key is optional and user-paid. However, it does not explicitly tell when not to use or list 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 the full burden of behavioral disclosure. It explains that Pipeworx 'picks the right tool, fills the arguments, and returns the result,' which covers the automation aspect. However, it lacks details on error handling, rate limits, authentication needs, or what happens if no data source is found. The description adds some context but is incomplete for behavioral 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 front-loaded with the core functionality in the first sentence, followed by explanatory details and examples. Every sentence earns its place by clarifying usage, benefits, or providing concrete examples. It is appropriately sized and structured for easy comprehension.

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 querying with automated tool selection) and no annotations or output schema, the description does a good job explaining the purpose and usage. However, it lacks details on output format, error cases, or limitations, which would be helpful for completeness. The examples partially compensate, but some gaps remain.

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, with the 'question' parameter documented as 'Your question or request in natural language.' The description reinforces this by stating 'Ask a question in plain English' and providing examples, adding practical meaning beyond the schema. Since there's only one parameter, the baseline is high, and the description effectively complements 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: 'Ask a question in plain English and get an answer from the best available data source.' It specifies the verb ('ask'), resource ('answer'), and mechanism ('Pipeworx picks the right tool, fills the arguments'). It distinguishes from siblings by emphasizing natural language input versus specific tool selection.

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 when to use this tool: 'No need to browse tools or learn schemas — just describe what you need.' It provides clear alternatives by implication (use other tools for specific, schema-driven queries) and includes examples ('What is the US trade deficit with China?', etc.) to illustrate appropriate 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 mark as read-only and non-destructive. The description adds that it fans out to appropriate data packs, resolves market, classifies bet, and returns an evidence packet plus a comparison. This provides rich behavioral detail beyond the annotations, with 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 a single dense paragraph but every sentence adds value. It is front-loaded with the core action. While it could be split for readability, it is well-structured and concise for the amount of information conveyed.

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

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

The tool has no output schema, but the description explains the return type: an evidence packet plus market-vs-model comparison. It covers resolution, classification, and fan-out processes. No error handling mentioned, but for a core demo tool with simple params, it is adequately 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 good descriptions. The description adds meaning for both parameters: elaborates on the market parameter (accepts slug, URL, or text) and explains the depth parameter's meaning ('quick = 2-3 sources, thorough = full fan-out') and default. This adds value over 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: researching Polymarket bets by pulling Pipeworx data. It uses a specific verb and resource ('Research a Polymarket bet') and distinguishes from siblings like 'ask_pipeworx' by emphasizing that it's the core demo product that combines multiple data sources in one call.

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 use cases: 'Use for "should I bet on X?" ...'. It contrasts with the alternative of discovering packs manually, but does not explicitly list alternative tools or when not to use this tool. Therefore, it is clear but lacks exclusions, scoring 4.

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 bears full responsibility. It discloses that the tool returns paired data and pipeworx:// URIs, and details type-specific outputs. However, it omits potential side effects, rate limits, or error handling, leaving some behavioral ambiguity.

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 the core function and then specifics. No extraneous words; every sentence adds value. It is appropriately sized for the tool's simplicity.

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 two parameters, 100% schema coverage, and no output schema or annotations, the description adequately explains the return data for each type. It is complete enough for most use cases, though additional details on ordering or error states would be beneficial.

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 clear descriptions for both parameters. The description adds valuable context beyond the schema by specifying exactly which data fields are returned for each type (e.g., revenue, net income for companies), enriching the agent's 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 it compares 2-5 entities side by side, specifying the data returned for each type (company: financial metrics; drug: regulatory counts). It distinctly differentiates from sibling tools like get_air_quality or get_apod, which fetch single data points.

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 mentions it replaces 8-15 sequential agent calls, implying efficiency for multi-entity comparisons. However, it does not explicitly state when not to use or list alternative tools, though sibling diversity makes context 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 provided, the description carries the full burden and does well by explaining key behavioral traits: it's a search operation ('Search the Pipeworx tool catalog'), returns results ('Returns the most relevant tools with names and descriptions'), and has a specific use case context ('500+ tools available'). It doesn't mention rate limits or authentication needs, but covers the core behavior adequately.

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 concise with two sentences that each earn their place: the first explains what the tool does, the second provides crucial usage guidance. No wasted words, front-loaded with core functionality.

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 search tool with no annotations, 100% schema coverage, but no output schema, the description is quite complete. It explains purpose, usage context, and behavior. The main gap is not describing the return format in detail, but given the tool's relative simplicity, this is a minor omission.

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 fully documents both parameters. The description doesn't add any parameter-specific information beyond what's in the schema, maintaining the baseline score of 3 for adequate but no extra 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 tool's purpose with specific verbs ('Search the Pipeworx tool catalog') and resources ('tool catalog'), and explicitly distinguishes it from siblings by mentioning it's for discovering tools among '500+ tools available' when other tools are specific data retrieval functions.

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 guidance: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This gives clear when-to-use instructions and implies alternatives (use other tools once you've discovered the right ones).

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, but the description discloses return format (citation URIs), data types included, and that it replaces many calls. Lacks explicit mention of read-only or rate limits but sufficient.

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 list, front-loaded with purpose. Every sentence adds value with no redundancy.

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

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

For a complex tool bundling multiple sources with no output schema, it explains return value and data types. Could mention limits/pagination but overall 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%. Description adds context: 'type' currently only 'company', 'value' as ticker or CIK, and notes names require resolve_entity, adding value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to retrieve a full entity profile across Pipeworx packs. It lists specific data types for 'company' and distinguishes from siblings like resolve_entity.

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 (general entity profile) and when not (federal contracts, use usa_recipient_profile). Also implies names need resolve_entity first.

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. While 'Delete' implies a destructive operation, the description doesn't specify whether deletion is permanent, reversible, requires specific permissions, or has side effects. It also doesn't mention what happens if the key doesn't exist or describe the response format.

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 functionality without any wasted words. It's appropriately sized for a simple tool with one parameter.

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 operation with no annotations and no output schema, the description is insufficient. It doesn't explain what constitutes a 'stored memory', whether deletion has confirmation steps, what the response looks like, or how this tool relates to sibling memory operations. The context signals indicate this is a mutation tool that needs more behavioral disclosure.

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 single parameter 'key' documented as 'Memory key to delete'. The description adds minimal value beyond this, only restating that deletion is by key. With complete schema coverage, the 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 action ('Delete') and resource ('a stored memory by key'), making the purpose immediately understandable. However, it doesn't distinguish this tool from potential siblings like 'recall' or 'remember' that might also interact with memories, 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. With siblings like 'recall' and 'remember' that likely interact with the same memory system, there's no indication of when deletion is appropriate versus retrieval or storage operations.

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?

Describes core behavior (fetch page, extract title/description/key links, output markdown) beyond annotations (readOnly, idempotent, non-destructive). 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?

Single paragraph with clear front-loading of purpose. A sentence could be trimmed but overall effective and easy to parse.

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

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

No output schema, but description fully explains the output format (markdown text blob ready for site-root/llms.txt) and the extraction process, leaving no critical 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 coverage is 100%, so baseline is 3. Description does not add new meaning to parameters beyond what the schema provides, but it is acceptable as the schema is self-documenting.

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 for any URL, matching the name and distinguishing it from sibling tools like ai_visibility_check or 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?

Provides explicit use cases: indexing client sites, drafting for own projects, auditing competitors. Lacks alternative recommendations but is sufficiently directive.

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 what the tool does but doesn't describe important behavioral aspects: what 'near a location' means (radius, precision), what measurements are returned (PM2.5, AQI, etc.), whether there are rate limits, authentication requirements, or error conditions. The description is functional but lacks operational 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 a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose and includes all essential elements: action, resource, location context, and data source. Every word earns its place.

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 2-parameter tool with no annotations and no output schema, the description provides adequate basic context about what the tool does. However, it lacks important operational details that would be helpful for an AI agent: what format/units the measurements are in, what 'near' means, typical response structure, or any limitations. The description is minimally complete but could be more informative.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters (latitude, longitude) with basic descriptions. The description adds context that these parameters define 'a location' for air quality measurements, but doesn't provide additional semantic details beyond what the schema states. This meets 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 verb ('Get') and resource ('air quality measurements') with source attribution ('from OpenAQ') and location context ('near a location'). It doesn't differentiate from siblings, which are unrelated (APOD, earthquakes, ISS location), but that's not needed here since they serve completely different domains.

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?

No guidance is provided about when to use this tool versus alternatives. The description mentions 'from OpenAQ' which implies this is the data source, but there's no discussion of when to choose this over other air quality APIs or tools, nor any prerequisites or constraints for usage.

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 what the tool does but doesn't cover key traits like rate limits, authentication needs, error handling, or what happens if an invalid date is provided. This is a significant gap for a tool with no annotation coverage.

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 without any wasted words. It's appropriately sized for a simple tool, earning a high score for conciseness.

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

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

Given the tool's low complexity (1 optional parameter, no output schema, no annotations), the description is minimally adequate but lacks completeness. It doesn't explain return values or potential errors, which would be helpful since there's no output schema, leaving gaps in understanding the tool's full behavior.

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, with the 'date' parameter documented as 'Date in YYYY-MM-DD format (default: today)'. The description doesn't add any meaning beyond this, so it meets the baseline of 3 where 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 tool's purpose with a specific verb ('Get') and resource ('NASA Astronomy Picture of the Day'), making it immediately understandable. However, it doesn't differentiate from sibling tools (e.g., get_air_quality, get_earthquakes), which are distinct but not directly comparable, so a 4 is appropriate rather than a 5.

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, such as whether it's for current or historical images, or if there are limitations like date ranges. It lacks explicit context or exclusions, leaving usage implied at best.

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. 'Get recent earthquakes' implies a read-only operation, but the description doesn't explicitly state this. It also doesn't mention rate limits, authentication requirements, data freshness, or what format/scope the data returns. For a data retrieval 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 functionality without any wasted words. It's appropriately sized for a simple data retrieval tool and front-loads the essential information. Every word earns its place in this minimal description.

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 (2 parameters, no output schema, no annotations), the description is insufficiently complete. It doesn't explain what data is returned, in what format, or any limitations of the USGS data source. Without annotations or output schema, the agent has no information about the response structure or behavioral constraints beyond the basic 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?

The input schema has 100% description coverage, with both parameters clearly documented in the schema itself. The description doesn't add any parameter information beyond what's already in the schema. According to the scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in the description, which applies here.

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 ('Get') and resource ('recent earthquakes from USGS'), making the purpose immediately understandable. It doesn't distinguish from sibling tools (which are unrelated geospatial/astronomy APIs), but that's not necessary since they serve completely different domains. The description is specific enough for the agent to understand this is a data retrieval tool for earthquake information.

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. While the sibling tools are unrelated (air quality, astronomy picture, ISS location), there's no mention of whether this is the primary earthquake data source, if there are other earthquake tools, or any prerequisites for use. The agent must infer usage purely from the tool name and description.

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 what the tool does but doesn't describe how it behaves: Is it real-time or cached data? What's the update frequency? Are there rate limits? Does it require authentication? For a tool with zero annotation coverage, this is a significant gap 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 a single, clear sentence that states exactly what the tool does with zero wasted words. It's appropriately sized for a simple zero-parameter tool and is perfectly front-loaded with the essential 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?

For a simple zero-parameter tool with no output schema, the description adequately covers the basic purpose. However, without annotations or output schema, it lacks important behavioral context about data freshness, reliability, and format. The description is complete enough for basic usage but leaves gaps that could affect agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters with 100% schema description coverage, so the schema already fully documents the input requirements. The description appropriately doesn't waste space discussing parameters that don't exist. A baseline of 4 is appropriate for zero-parameter tools where the description focuses on purpose rather than input semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('current location of the International Space Station'). It distinguishes from siblings by focusing on ISS location rather than air quality, astronomy pictures, or earthquakes. However, it doesn't explicitly differentiate from hypothetical similar tools like 'get_iss_crew' or 'get_iss_speed', so it's not a perfect 5.

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. It doesn't mention any prerequisites, timing considerations, or comparisons to sibling tools. The agent must infer usage from the name and description alone without explicit 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?

No annotations provided, but description discloses rate limiting and that it's free. Lacks details on what happens after submission (e.g., confirmation or processing). Still adequate for a simple 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?

Four sentences, each serving a purpose: (1) states purpose and usage types, (2) instructions on content, (3) negative instruction (no prompt verbatim), (4) rate limit. No fluff.

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

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

No output schema, so description should hint at return value—it doesn't. But feedback tool likely returns a success message; still, completeness is high for a simple tool with nested object and enum parameters.

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 coverage, baseline is 3, but description adds substantial value: explains each enum option for 'type', gives guidance on 'message' content and length, and describes optional 'context' fields. Goes well 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's purpose: sending feedback to the Pipeworx team. It lists specific use cases (bug reports, feature requests, missing data, praise) and distinguishes it from siblings focused on data retrieval or memory.

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 guidelines: when to use (listed use cases), what to include (describe in terms of Pipeworx tools/data), what not to include (end-user prompt verbatim), and rate limits (5/day). Clearly differentiates from other tools on the server.

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

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

Beyond annotations (readOnlyHint, etc.), the description adds that the data is self-aggregating from CF analytics engine, no PII, and cached 5min-1h. This provides 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?

Three well-structured sentences. No fluff. Front-loaded with purpose, followed by use cases and behavioral details. Every sentence earns its place.

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 (1 optional param, no output schema), the description covers purpose, usage, output nature, data source, caching, and privacy. Fully adequate for an agent to decide.

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 a detailed description of the 'window' parameter. The tool description reiterates and slightly augments (e.g., 'shorter windows surface what's hot now') but does not add critical new info.

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 trending tools, packs, and call volume over a window. It uses specific verbs and resources, and is distinct from sibling tools like '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?

Three explicit use cases are provided, and the caching behavior is noted. It does not compare directly with alternatives, but the usage contexts are clear and actionable.

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: true and destructiveHint: false. The description adds behavioral details about the search and monotonicity checking logic, and mentions the output includes ranked opportunities with reasoning. It does not contradict annotations and provides reasonable transparency, though it could mention data freshness or external dependencies.

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 purpose and then efficiently explains the two modes with examples. 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 (two modes, cross-event discovery) and the absence of an output schema, the description adequately covers expected input, behavior, and output (ranked opportunities with reasoning). It is complete for an agent to decide when and how to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions. The description significantly adds semantic value by explaining the two parameters in the context of the two modes, providing real examples (e.g., 'when-will-bitcoin-hit-150k' and 'Strait of Hormuz traffic returns to normal'), which is far beyond the schema's brief 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 finds arbitrage opportunities on Polymarket via monotonicity violations, and explicitly describes two distinct modes (event and topic) with examples. It provides a specific verb ('find') and resource ('arbitrage opportunities on Polymarket'), and the modes differentiate its usage from potential confusion with sibling 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 gives clear guidance on when to use each mode: event mode for single events and topic mode for cross-event searches. It explains why topic mode is necessary ('single-event mode misses the May≤June rule'), effectively telling the agent when to choose one over the other.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds detailed behavioral context: how it groups by asset, fetches price history once, computes model probability, and ranks by edge. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a well-structured paragraph with front-loaded purpose, followed by methodology and use case. It is appropriately sized for the complexity, though slightly verbose.

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 full schema coverage, no output schema, and a detailed description covering process and intent, it is nearly complete. It could mention return format but is sufficient.

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 adequate descriptions. The description adds minimal extra meaning beyond restating schema information (e.g., 'Top N edges to return after ranking' for limit). Baseline 3 applies.

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 scans high-volume Polymarket markets and returns those with greatest disagreement between Pipeworx data and market price. It specifies the model, process, and output, and distinguishes from siblings like polymarket_arbitrage by focusing on opportunity 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 targets the 'what should I bet on today' use case, implying when to use for discovery. It lacks explicit 'when not to use' or alternative tools, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it explains the reason for price differences (different participant pools), the return format (leg-by-leg prices and spread), and the units. It does not mention rate limits or error handling, but for a read-only tool with good annotations, this is sufficient.

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 opening sentence, context, two modes, and return format. It uses parentheses and capitalization for emphasis. While slightly verbose, each sentence adds value and there is no 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 complexity of cross-venue spread calculation and absence of output schema, the description adequately explains the return values (leg prices in 0-1, spread in percentage points) and the spread direction (Kalshi minus Polymarket). It also provides context for why spreads occur. Missing details about error scenarios or update frequency, but overall complete for the tool's scope.

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%, but the description adds significant meaning beyond the schema: it explains the 'topic' pre-mapped shortcuts and how explicit tickers override topic mapping. This gives clear guidance on parameter usage and interaction.

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 as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question. It specifies the two modes of operation (topic shortcuts and explicit tickers) and distinguishes it from sibling tools like 'polymarket_arbitrage' by focusing on two specific 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 provides clear usage guidance: it explains two modes (topic for pre-mapped macros, explicit for custom pairings) and the context of arb signal. It lacks explicit when-not-to-use or comparison with siblings, but the mode differentiation is effective for selecting the right input.

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 key behavioral traits: retrieval vs. listing based on parameter presence, persistence across sessions, and that memories are 'previously stored' (implying 'remember' must be used first). However, it doesn't mention error handling (e.g., if key doesn't exist), return format, or any rate limits. The description adds useful context but lacks comprehensive behavioral details.

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 the core functionality, and every phrase earns its place. The first sentence states the dual operations, and the second provides usage context without redundancy. It's efficiently structured and avoids unnecessary 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 moderate complexity (retrieval/listing with one optional parameter), no annotations, and no output schema, the description is largely complete. It covers purpose, usage, and parameter semantics well. However, it lacks details on return values (e.g., format of retrieved memory or list) and error cases, which would be helpful for an agent. It compensates somewhat with clear behavioral context but has minor 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 schema already documents the optional 'key' parameter. The description adds meaningful semantics by explaining the conditional behavior: 'omit to list all keys' clarifies the dual functionality. It also ties the parameter to 'memory key to retrieve' and 'context you saved earlier', providing context beyond the schema's technical description. With 0 required parameters, this exceeds 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 with specific verbs ('retrieve', 'list') and resources ('previously stored memory by key', 'all stored memories'). It distinguishes from siblings like 'remember' (which stores) and 'forget' (which removes). The phrase 'context you saved earlier' reinforces the retrieval function.

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 when to use this tool ('to retrieve context you saved earlier') and provides clear conditional usage ('omit key to list all keys'). It distinguishes from alternatives by referencing 'saved earlier in the session or in previous sessions', implying 'remember' is for saving. No misleading guidance is present.

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 of behavioral disclosure. It details that the tool fans out to multiple sources (SEC EDGAR, GDELT, USPTO), accepts both ISO and relative dates, and returns structured data with URIs. It does not disclose potential rate limits, permissions, or error handling, but the core behavior is well explained.

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 dense paragraph with no wasted words. It covers purpose, behavior, parameters, and return format in a few sentences. While not broken into sections, it is efficient and front-loads 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 has 3 required parameters and no output schema, the description provides a good overview of input formats and return structure (structured changes, total_changes, URIs). It lacks details on error cases or limitations, but for a tool of this complexity, it is reasonably 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%, so baseline is 3. The description adds value by clarifying that 'since' accepts both ISO and relative formats with examples, and suggests typical monitoring values ('30d' or '1m'). It also explains that 'value' can be a ticker or CIK. This goes beyond the schema's 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 changes for an entity since a point in time. It provides specific examples for the 'company' type and mentions the overall behavior. However, it does not explicitly distinguish this tool from sibling tools like entity_profile or compare_entities, missing an opportunity for differentiation.

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 includes explicit usage guidance: 'Use for "brief me on what happened with X" or change-monitoring workflows.' This gives concrete scenarios but does not mention when not to use it or provide alternatives, so it is clear but not exhaustive.

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 persistence model (authenticated users get persistent memory, anonymous sessions last 24 hours) and the scope (session memory for cross-tool context). It does not cover aspects like rate limits or error conditions, but the disclosed traits are highly relevant for tool selection.

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 efficiently structured in two sentences: the first states the core purpose with examples, and the second adds critical behavioral context about persistence. Every sentence earns its place with no redundant or vague language, making it easy to parse.

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 (storage with persistence rules), no annotations, and no output schema, the description does well by covering purpose, usage, and key behavioral traits. It lacks details on return values or error handling, but for a storage tool, the provided information is largely complete for effective agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents both parameters ('key' and 'value'). The description adds minimal value beyond the schema by implying the parameters are used for storage but does not provide additional syntax, format, or constraints. This meets 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 ('Store a key-value pair') and resource ('in your session memory'), distinguishing it from sibling tools like 'recall' (likely for retrieval) and 'forget' (likely for deletion). It provides concrete examples of what can be stored ('intermediate findings, user preferences, or context across tool calls'), making the purpose 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 explicitly states when to use this tool ('to save intermediate findings, user preferences, or context across tool calls'), providing clear context. However, it does not mention when NOT to use it or explicitly name alternatives (e.g., 'recall' for retrieval), which prevents a perfect score.

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 supported type (company), accepted input formats, and return fields (ticker, CIK, name, URIs). However, it lacks details about error handling, idempotency, rate limits, or whether it's read-only. For a simple lookup, this is adequate but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences long, with the primary purpose in the first sentence, followed by specific details and a clear benefit. Every sentence adds value, and there is no redundancy or fluff.

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

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

For a tool with two parameters, no output schema, and no annotations, the description provides all essential information: purpose, input requirements, output content, and value proposition. It is complete for a straightforward lookup 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?

Although the input schema already describes parameters with 100% coverage, the description adds valuable context: it provides concrete examples for 'value' (AAPL, 0000320193, Apple), explains the purpose of canonical IDs, and clarifies versioning (v1: company). This goes 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 resolves an entity to canonical IDs, specifies it's for companies in v1, and provides concrete examples (ticker, CIK, name). It distinguishes itself from unrelated siblings and highlights unique value (replaces 2-3 lookup calls).

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 efficient usage compared to multiple lookups ('Replaces 2–3 lookup calls'), but does not explicitly state when not to use or name alternatives. Given that sibling tools are unrelated, 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, idempotentHint, openWorldHint, and no destructiveness. Description adds specific behaviors: probes each entity, ranks by score, surfaces most/least recognized, returns 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?

Two sentences plus an example. Front-loaded with purpose, no redundant information. Every sentence earns its place.

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

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

Covers purpose, usage, and output fields (score, confidence, signal density). No output schema, but description compensates. Minor missing details like pagination or rate limits, but overall sufficient for 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?

Schema description coverage is 100%, so baseline is 3. Description adds value for 'entities' parameter (first entry treated as subject), improving semantics. Other parameters are adequately described in schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (likely different 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?

Explicitly mentions use case: competitive AI-marketing audits, with example question. Implies when to use (multiple entities) and that first entity is subject. Does not explicitly state when not to use, but sibling differentiation 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?

No annotations exist, so the description carries full burden. It discloses the returned verdict types, structured form, actual value with citation, and percent delta. It does not mention any destructive behavior or auth needs, but overall it is transparent about operations.

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 contains no unnecessary words. 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 tool has one parameter, no output schema, and no annotations, the description is sufficiently complete. It explains input, output scope, supported claim types, and the value proposition of replacing multiple calls.

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 'claim' is described in the schema with examples. The description adds context that it is a natural-language claim and gives additional examples, enhancing 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 fact-checks claims against authoritative sources, specifies scope (company-financial claims for US public companies), and mentions it replaces multiple agent calls. However, it does not explicitly distinguish from sibling tools like 'ask_pipeworx' 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?

The description specifies that v1 supports only company-financial claims for public US companies, implying when to use and limitations. It does not explicitly state alternatives or when-not-to-use, but the scope is clearly defined.

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