worlduank

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, indicating safe, non-destructive operations. The description adds behavioral details: it explains the free default model, the need for a BYO API key for Anthropic, and the return format (per-model fields and combined view). No contradictions with annotations.

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

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

The description is a single, well-structured paragraph with the main action upfront, followed by details on defaults, optional parameters, and use cases. Every sentence adds value, and there is no redundancy or verbose language.

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 covers return values ('per-model {score, confidence, signals, raw_response} + a combined view'). It also explains parameter interactions (e.g., models requiring _apiKey) and provides example use cases, making it complete for an agent to understand and invoke the tool correctly.

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

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

Schema description coverage is 100% (all parameters have descriptions). The tool description reinforces the purpose of each parameter (e.g., 'models' lists supported models, '_apiKey' explains it's for Anthropic) but does not add substantial new meaning beyond the schema. The description provides context but not additional semantic depth.

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 action ('Probe one or more LLMs') and resource ('for what they know about a business / brand / product / topic'), and it outputs a visibility score (0-100) per model. It distinguishes itself from siblings by focusing on AI visibility checks, a unique function among the listed 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 provides clear context for when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and how to add Anthropic. However, it does not explicitly state when not to use it or mention alternative tools, though this is partially compensated by the specific 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?

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: the tool selects data sources and fills arguments automatically, and it handles natural language queries. However, it lacks details on limitations (e.g., query complexity, data freshness, error handling) or operational constraints (e.g., rate limits, authentication needs).

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, followed by practical guidance and concrete examples. Every sentence adds value: the first explains the tool's role, the second highlights its automation benefits, and the third provides illustrative use cases. No redundant or verbose content.

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

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

Given the tool's complexity (natural language processing and tool selection) and lack of annotations/output schema, the description is reasonably complete. It covers the purpose, usage, and input semantics well. However, it could better address behavioral aspects like performance or limitations to fully compensate for missing structured 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?

The schema description coverage is 100%, with one parameter ('question') fully documented. The description adds semantic context by framing it as 'plain English' questions and providing examples, which clarifies the expected input format beyond the schema's 'natural language' description. Since there's only one parameter, the baseline is high.

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 structured 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 provides usage guidance: 'No need to browse tools or learn schemas — just describe what you need.' It contrasts with sibling tools (like discover_tools or specific data tools) by positioning this as a high-level, simplified interface. Examples further clarify 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 indicate read-only and non-destructive. The description adds context: it resolves markets, classifies bets, fans out to packs, and returns a comparison. It does not detail rate limits or auth, but the added behavior is valuable.

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

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

The description is three sentences, all substantive. The first sentence defines input and purpose, the second explains the process, the third lists use cases. It is efficient but not overly terse.

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 (multi-source fan-out, classification, comparison), the description covers what it does, what it returns, and how to use it. No output schema, but the return type is described sufficiently.

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

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

Schema coverage is 100%, yet the description adds meaning: it explains that 'market' can be a slug, URL, or question text, and describes 'depth' options (quick vs thorough) and the default. This enriches 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 researches a Polymarket bet by pulling Pipeworx data. It specifies input formats (slug, URL, question text) and output (evidence packet + comparison). This distinguishes it from siblings like validate_claim or get_gdp.

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

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

The description explicitly lists use cases: 'should I bet on X?', 'what does the data say?', 'is there edge?'. It also notes this is the core demo product and that agents benefit from its bundled approach. No explicit exclusions, 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?

No annotations provided; description carries burden. Discloses returned data (revenue, net income, etc.) and output format (paired data + resource URIs). Implies read-only behavior from context, but does not explicitly state safety characteristics.

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 with no wasted words. Front-loads the purpose, provides key details, and ends with the efficiency benefit.

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 all aspects: purpose, parameters, data returned, and output format. No output schema, so description adequately explains return values.

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 significant value by explaining the meaning of each enum value and providing concrete examples for the values array. Also ties parameters to the data returned.

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 in one call, with specific details for company and drug types. Distinguishes from siblings by offering batch comparison that replaces 8-15 sequential 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?

Describes when to use (comparing entities) and gives examples for each type. Does not explicitly state when not to use, but sibling tools don't overlap heavily, so 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?

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: it's a search operation (implied read-only, though not explicitly stated), returns a list of tools with names and descriptions, and has a default/max limit context (though this is also in the schema). However, it doesn't mention potential limitations like rate limits, authentication needs, or error handling, 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 appropriately sized and front-loaded, with two sentences that efficiently convey purpose and usage guidelines. Every sentence earns its place by providing essential information without redundancy or unnecessary details, making it easy for an agent to quickly understand the tool's role.

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 (search functionality with 2 parameters) and no output schema, the description is mostly complete. It covers purpose, usage context, and return format (tools with names and descriptions), but lacks details on output structure (e.g., pagination, error cases) and behavioral aspects like rate limits. However, it provides enough context for an agent to use it effectively in most scenarios.

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 (query and limit) thoroughly. The description adds minimal value beyond the schema by implying the query should be a natural language description of a task, but doesn't provide additional syntax or format details. This meets the baseline of 3 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 tool's purpose with specific verbs ('Search the Pipeworx tool catalog') and resources ('tool catalog'), and distinguishes it from siblings by emphasizing its role in discovery rather than direct data retrieval. It explicitly mentions returning 'the most relevant tools with names and descriptions', which differentiates it from the sibling tools that fetch specific data like GDP or population.

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.' It also implies an alternative approach by suggesting not to use it when you already know which tools to use, effectively distinguishing it from the sibling tools that are for direct data access.

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 fully discloses the read-only nature and the data returned (SEC filings, patents, etc.), and mentions performance benefit of replacing multiple calls.

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

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

Three concise sentences, front-loaded with purpose, then details, then a usage note. 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?

Covers what is returned and how to call, but no output schema provided; still, description is sufficient for an agent to invoke correctly.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by explaining value types (ticker or CIK) and instructing to use resolve_entity for names.

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 returns a full profile of an entity across multiple packs, with specific data types for company, and distinguishes from sibling tools by listing what is included.

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

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

Explicitly states when to use (for company profiles), when not to use (for federal contracts, use usa_recipient_profile), and prerequisites (use resolve_entity if only have a name).

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. While 'Delete' implies a destructive operation, it doesn't specify whether deletion is permanent, reversible, requires specific permissions, or what happens on success/failure. For a destructive tool with zero annotation coverage, this is a significant gap in 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 a single, efficient sentence that communicates the core purpose without unnecessary words. It's appropriately sized for a simple tool with one parameter and is 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 destructive tool with no annotations and no output schema, the description is incomplete. It doesn't address what happens after deletion (e.g., confirmation message, error if key doesn't exist), behavioral implications, or how it fits within the broader memory system alongside sibling tools. The description should do more given the tool's complexity and lack of structured metadata.

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 has 100% description coverage, with the 'key' parameter already documented as 'Memory key to delete.' The description adds no additional semantic context beyond what the schema provides, such as key format examples or constraints. Baseline 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 resource ('a stored memory by key'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'recall' or 'remember' which likely interact with the same memory system.

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. There's no mention of prerequisites (e.g., needing an existing memory key), error conditions, or how it differs from sibling tools like 'recall' (which presumably retrieves memories) or 'remember' (which presumably creates them).

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 details: fetches the page, extracts title/description/key links, and emits markdown. Consistent with annotations and provides additional context.

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

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

Three sentences with no waste. Front-loaded with purpose, followed by process and use cases. Highly efficient.

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

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

Given no output schema, the description explains the output (text blob) and process. It covers input, behavior, and output format sufficiently for a simple tool.

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

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

Schema coverage is 100%, so both parameters are well-described in the schema. The description does not add significant new meaning beyond the schema, meeting 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 generates an llms.txt file for AI crawlers, with specific verb 'generate' and resource 'llms.txt file'. It distinguishes from sibling tools which are unrelated.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting llms.txt for own project, or auditing competitor. It does not mention when not to use or alternatives, but the provided usage contexts are 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 of behavioral disclosure. It clearly indicates this is a read operation ('Get') and specifies the input format, but doesn't mention potential limitations like error handling, data freshness, or rate limits. The description adds useful context about what data is returned, compensating partially for the lack of 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 perfectly concise with two sentences: the first states the purpose and data returned, the second specifies the input format with examples. Every word earns its place with zero redundancy, and the information is front-loaded appropriately.

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 read tool with one parameter and no output schema, the description is reasonably complete. It covers the purpose, data returned, and input requirements. The main gap is the lack of output format details, but given the tool's simplicity and the clear data fields listed, 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?

The schema description coverage is 100%, so the schema already documents the single parameter thoroughly. The description adds minimal value beyond the schema by repeating the ISO code format examples, but doesn't provide additional semantic context about parameter behavior or constraints.

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 ('basic information about a country'), listing key data fields (full name, region, income level, capital city, coordinates). It distinguishes from siblings by focusing on general country info rather than specific metrics like GDP or population.

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 for when to use this tool (to retrieve basic country information) and specifies the required input format (ISO 3166-1 codes). However, it doesn't explicitly state when not to use it or name alternatives among sibling tools, though the distinction is implied by the different data focus.

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. While it states what the tool does, it doesn't describe important behavioral aspects like whether this is a read-only operation, what format the data returns in, whether there are rate limits, or what happens with invalid country codes. For a tool with no annotation coverage, this is a significant gap.

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 states the core purpose, the second provides crucial sibling differentiation. There's zero wasted language and it's effectively front-loaded with the most important 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 single-parameter read tool with 100% schema coverage, the description provides adequate context about purpose and sibling relationships. However, with no output schema and no annotations, it doesn't describe what format the GDP data returns in (time series? single value? error handling?), which leaves gaps in understanding the tool's complete 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?

Schema description coverage is 100%, so the schema already fully documents the single parameter (country_code with ISO code format). The description doesn't add any parameter-specific information beyond what's in the schema, so the baseline score of 3 is appropriate when the schema does all the parameter documentation work.

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 GDP'), resource ('current USD over time for a country'), and scope ('shortcut for get_indicator with NY.GDP.MKTP.CD'). It precisely distinguishes this tool from its sibling 'get_indicator' by specifying it's a specialized version for GDP data.

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

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

The description explicitly states when to use this tool ('shortcut for get_indicator with NY.GDP.MKTP.CD'), providing clear context and an alternative (using get_indicator directly). This gives the agent perfect guidance on when this specialized tool is appropriate versus the more general sibling.

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 retrieving time-series values but lacks details on permissions, rate limits, data freshness, or error handling. This is a significant gap for a data-fetching tool with no structured safety hints.

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 a clear purpose in the first sentence and efficient examples in the second. Every sentence adds value without redundancy.

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

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

Given no annotations and no output schema, the description is incomplete. It covers the basic purpose and parameters but lacks details on return values, error cases, or behavioral constraints, which are needed for a tool fetching time-series 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%, so the schema already documents all parameters. The description adds value by providing common indicator examples (e.g., NY.GDP.MKTP.CD) and implying time-series output, but it does not explain parameter interactions or formats beyond what the schema provides.

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

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

The description clearly states the specific action ('Get time-series values') for a specific resource ('World Bank indicator for a specific country'), distinguishing it from siblings like get_gdp or get_population by indicating it handles multiple indicators through codes.

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 by listing common indicator examples (e.g., GDP, population), which helps guide usage, but it does not explicitly state when to use this tool versus alternatives like get_gdp or get_population, nor does it mention 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 full burden. While it mentions this is a 'shortcut' for another tool, it doesn't disclose key behavioral traits like whether this is a read-only operation, what format the 'over time' data returns (e.g., time series), potential rate limits, or error conditions. The description adds minimal behavioral context beyond the basic purpose.

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: the first states the purpose, and the second provides crucial usage guidance. Every word earns its place, and it's front-loaded with the 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?

Given the tool's low complexity (single parameter, no annotations, no output schema), the description is adequate but has gaps. It explains the purpose and sibling relationship well, but without annotations or output schema, it should ideally mention more about the return format (e.g., time series data) or behavioral constraints to be fully complete.

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

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

Schema description coverage is 100%, so the schema already fully documents the single parameter 'country_code' with its type, requirement, and format example. The description doesn't add any parameter-specific information beyond what the schema provides, maintaining the baseline score of 3.

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

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

The description clearly states the specific action ('Get total population over time') and resource ('for a country'), and explicitly distinguishes this tool from its sibling 'get_indicator' by calling it a 'shortcut' for that specific indicator code. This provides excellent 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 explicitly states when to use this tool versus alternatives: it's a 'shortcut for get_indicator with SP.POP.TOTL.' This tells the agent precisely when to choose this tool (for population data) versus the more general 'get_indicator' tool or other siblings like 'get_country' or 'get_gdp'.

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 disclosing behavioral traits. It reveals rate limiting (5 messages per identifier per day) and content restrictions (no end-user prompt verbatim). This is sufficient for a simple feedback tool, though it doesn't describe the acknowledgement or processing 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 extremely concise: three sentences that front-load purpose, then enumerate use cases, guidelines, and rate limits. No redundant or filler content; every sentence is 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?

Given the tool's simplicity (3 parameters, no output schema), the description covers purpose, usage context, and behavioral constraints. It lacks explicit mention of what the identifier for rate limiting is (e.g., user ID or API key), but overall it is adequate for an AI agent to invoke correctly.

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

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

Schema description coverage is 100%, but the description adds value by instructing users to 'Describe what you tried in terms of Pipeworx tools/data' and to exclude the end-user's prompt. This goes beyond the schema's parameter descriptions and provides practical usage context for the 'message' 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 verb 'Send' and the resource 'feedback to the Pipeworx team'. It lists specific use cases (bug reports, feature requests, missing data, praise) which distinguishes it from sibling tools that are data retrieval or memory 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 explicitly says when to use the tool ('Use for bug reports...') and provides guidance on what to include and exclude ('do not include the end-user's prompt verbatim'). It also mentions a rate limit, but does not explicitly state when not to use it or 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?

Beyond annotations (readOnlyHint, destructiveHint, etc.), the description adds caching behavior (5min-1h) and data provenance details (derived from analytics engine, no PII). This enriches the agent's understanding of what to expect.

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

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

The description is front-loaded with the core purpose and uses bullet points for use cases. Some phrases like 'Self-aggregating signal' are slightly redundant but do not detract significantly.

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

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

Given no output schema, the description explains the return structure adequately. It covers caching, data safety, and the single parameter's effect. For a read-only tool with clear annotations, this is complete.

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

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

With 100% schema coverage, the baseline is 3. The description adds interpretive value by explaining the trade-off between short and long windows ('surfaces what's hot right now' vs. 'steady-state demand'), going beyond the enum labels.

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

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

The description uses specific verbs ('returns', 'calling on Pipeworx') and clearly identifies the resource ('top tools, top packs, and total call volume over a recent window'). It distinguishes itself from siblings by focusing on aggregate usage trends rather than individual queries or entity profiles.

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, helping the agent decide when to invoke this tool. However, it does not explicitly state when not to use it or name alternative tools for different purposes.

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, non-destructive, and open-world behavior. The description adds behavioral context: the tool searches, groups markets, checks monotonicity, and returns ranked opportunities with reasoning. No contradictions. It does not discuss rate limits or auth, 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 efficiently structured: one sentence for purpose, then two bullet-like paragraphs for modes. It is dense but not verbose; every sentence contributes. However, it could be slightly trimmed without losing clarity.

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

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

The tool is moderately complex with two modes and no output schema. The description adequately explains the output (ranked opportunities with trade direction and reasoning). It covers the core logic and use cases, but omits details like pagination or error handling. Given no output schema, it is sufficiently 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%, but the description adds significant meaning: it defines each parameter's role, explains the two modes, and gives concrete examples (e.g., slug vs. topic). This far exceeds the schema's bare descriptions, enabling correct parameter selection.

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

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

The description clearly identifies the tool as finding arbitrage opportunities via monotonicity violations on Polymarket. It specifies two distinct modes (event and topic) and explains their scope, contrasting with siblings like polymarket_edges. The verb+resource (find arbitrage) is specific and actionable.

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 each mode: single-event for within an event, cross-event for across separate events. It highlights the cross-event mode's advantage for cases where cutoffs are separate events. While it doesn't list negative usage conditions, it provides clear contextual guidance.

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

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

Annotations already declare readOnlyHint=true and nondestructive=false. The description adds substantial behavioral details: it scans top markets, groups by asset, fetches price history once, computes model probability from FRED and live coinpaprika, and ranks by absolute edge. This goes well beyond the annotations, providing a clear algorithm and data source.

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 multi-sentence paragraph that is well-structured and front-loaded with the main purpose. Each sentence adds value, explaining the algorithm, data sources, and output. It is slightly verbose but still efficient.

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

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

Given the tool's complexity (scanning, grouping, modeling), the description fully explains the process, inputs, and output. There is no output schema, but the description mentions 'Returns top N ranked by edge magnitude with suggested trade direction,' which is adequate. No major 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 baseline is 3. The description does not add significant new meaning beyond the schema descriptions (limit, window, min_edge_pp). It mentions 'Top N edges to return after ranking' but that is already in the schema. No additional parameter-specific insight is provided.

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: 'Scan the highest-volume Polymarket markets and return the ones where Pipeworx data disagrees most with the market price.' It specifies the resource (Polymarket markets), the verb (scan and return), and the unique value proposition (edge discovery). It distinguishes from siblings like polymarket_arbitrage by focusing on model-based opportunities.

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 a clear use case: 'Built for the 'what should I bet on today' question — agents/users discover opportunities without paging through hundreds of markets by hand.' This tells when to use it. However, it does not explicitly exclude other scenarios or mention alternatives, but the context is sufficient.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds value by detailing the spread range (2-25pp) and the return structure (leg-by-leg prices and spread), which are not covered by 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 moderately concise and well-structured, with clear sections for modes and output. However, it could be slightly more succinct without losing clarity, but the current length is justified by the detail provided.

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

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

Despite lacking an output schema, the description adequately explains the return values. It covers both modes and provides examples, making it complete for a read-only tool that requires no additional context.

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, the description enhances understanding by explaining the topic shortcuts, providing concrete examples for explicit parameters, and clarifying that explicit tickers override topic mappings. This goes beyond the schema alone.

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

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

The description clearly defines the tool as computing cross-venue spreads between Kalshi and Polymarket. It specifies two distinct modes (topic and explicit tickers), making the purpose precise and differentiated from sibling tools like polymarket_arbitrage.

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

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

The description explains when to use the tool (to capture arb signals from venue price differences) and outlines two modes. However, it does not explicitly state when not to use it or compare it to alternative tools like polymarket_edges, 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?

With no annotations provided, the description carries full burden. It discloses key behavioral traits: the tool can retrieve from current or previous sessions, and it supports two modes (specific retrieval vs listing). However, it doesn't address important aspects like error handling (what happens if key doesn't exist), return format, or any 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?

Two sentences that efficiently convey all essential information with zero waste. The first sentence explains the dual functionality, the second provides usage context. Perfectly front-loaded and appropriately sized.

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

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

For a tool with no annotations and no output schema, the description provides adequate but incomplete coverage. It explains what the tool does and when to use it, but lacks details about return values, error conditions, and behavioral constraints that would be important for an AI agent.

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

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

The schema has 100% description coverage, so the baseline is 3. The description adds valuable semantic context beyond the schema: it explains that omitting the key triggers listing mode, and clarifies that memories can come from current or previous sessions. This compensates for the schema's purely technical description.

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

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

The description clearly states the tool's purpose with specific verbs ('retrieve', 'list') and resources ('previously stored memory', 'all stored memories'). It distinguishes from siblings like 'remember' (store) and 'forget' (delete) by focusing on retrieval 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 clear context for when to use the tool ('to retrieve context you saved earlier') and explains the two modes (retrieve by key vs list all). However, it doesn't explicitly state when NOT to use it or mention alternatives 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?

No annotations provided, but description covers fan-out parallelism, return structure (changes, count, URIs), and date format options. Missing info on rate limits or data freshness, but sufficient for a read-only 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 adding value. Front-loaded with purpose, no redundancy. Efficient.

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

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

Covers entity type limitation, date formats, fan-out, return values. No output schema, so return description is helpful. Edge cases not addressed 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 has 100% coverage with descriptions. Description adds relative date examples and typical monitoring values, enhancing usability 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?

Clear verb 'what's new' and resource 'entity since a given point in time'. Specific fan-out to SEC, GDELT, USPTO. Distinct from siblings like entity_profile or compare_entities.

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

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

Explicit usage examples: 'brief me on what happened with X' or change-monitoring. Does not state when not to use or name alternatives, 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 provided, the description carries the full burden of behavioral disclosure. It effectively explains key traits: the tool performs a write operation ('Store'), specifies persistence differences between authenticated users and anonymous sessions, and mentions the 24-hour limit for anonymous sessions. However, it lacks details on potential errors or limits on key/value size.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by usage context and behavioral details. Every sentence adds value without redundancy, making it efficiently structured and appropriately sized for the tool's complexity.

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 largely complete. It covers purpose, usage, and key behavioral aspects like persistence. However, it could benefit from mentioning the tool's return behavior or error cases to fully compensate for the lack of output schema.

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

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

The input schema has 100% description coverage, with clear documentation for both 'key' and 'value' parameters. The description does not add significant meaning beyond the schema, as it only implies the parameters without detailing syntax 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' (retrieval) and 'forget' (deletion). It specifies the storage mechanism and purpose, making the tool's function 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 clear context for when to use the tool ('to save intermediate findings, user preferences, or context across tool calls'), but does not explicitly mention when not to use it or name alternatives like 'recall' for retrieval. It offers practical guidance without 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 full burden. It mentions the output includes ticker, CIK, company name, and pipeworx:// URIs, implying a read-only lookup. However, it does not disclose potential errors, rate limits, or authentication needs. For a simple lookup tool, 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, covering purpose, specifics, and benefit without any redundant words. It is well-structured and front-loaded with the core action.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description provides sufficient context: input formats, output elements, and version constraint. An agent has enough information to decide correctly.

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

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

Schema coverage is 100%, and the description adds value by providing concrete examples (ticker like 'AAPL', CIK like '0000320193', name like 'Apple') which are more informative than the schema's generic 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 that the tool resolves an entity to canonical IDs across Pipeworx data sources, specifying the verb ('resolve'), the resource ('entity'), and the output (canonical IDs). It also distinguishes from siblings by noting it 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 provides clear context for when to use the tool ('in a single call') and its benefit over alternatives ('replaces 2–3 lookup calls'). It also notes the v1 limitation (only 'company' type). However, it does not explicitly state when not to use or list 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 already declare readOnly, openWorld, idempotent, non-destructive. The description adds value by explaining the internal probing via ai_visibility_check, ranking by score, and output structure (score, confidence, signal density). No contradictions.

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

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

Three sentences: purpose, process, and use case/output. No unnecessary words, front-loaded with the main verb 'Compare'.

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 purpose, process, output, and use case. It could mention the number of entities (2-8) and that it relies on ai_visibility_check, but overall it is complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with detailed descriptions. The description adds some context (e.g., 'First entry treated as the subject'), but does not significantly enhance parameter understanding beyond the schema. Baseline 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 compares AI visibility across multiple entities, uses ai_visibility_check internally, and produces a ranked list. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (more generic comparison).

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and explains the difference from ai_visibility_check. It could explicitly state when not to use this tool, but the context is sufficient for an agent to select it for multi-entity comparisons.

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 internal details: fans out to deps.dev and bundlephobia, mentions gracefull degradation with partial failures, and notes potential delay for first measurement (5-30s). Annotations already indicate read-only and idempotent, but description adds significant 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 sentences packed with information. Could be slightly more concise, but well-structured and front-loaded with the key purpose. 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?

No output schema, but description enumerates the fields in the summary block (is_latest, license, etc.) and mentions additional details (links, alternative versions). Provides complete picture of what the tool returns.

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

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

Schema coverage is 100% with good parameter descriptions. Description adds extra value by clarifying scoped packages are accepted and version defaults to latest, going beyond the schema.

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

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

Clearly states the tool is a composite check for npm packages, covering multiple aspects (license, advisories, bundle size, etc.). Distinguishes itself from sibling tools by being specific to npm ecosystem and aggregating multiple sources.

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: whenever an agent asks about safety, popularity, or cost of adding a package. Also specifies NPM only and mentions partial failure behavior.

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 fully discloses behavior: it returns a verdict, extracted structured form, actual value with citation, and percent delta. It implies a read-only operation and efficient multi-step replacement, but does not mention rate limits or auth needs.

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 (3 sentences) with front-loaded purpose, scope, and output details. Every sentence adds value without redundancy.

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

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

For a single-parameter tool with no output schema, the description fully covers supported claim types, outputs, and efficiency benefits. It stands alone without needing additional context.

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 clear description of the 'claim' parameter. The description adds examples but does not provide additional meaning beyond the schema.

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

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

The description explicitly states the tool's purpose: fact-check natural-language claims against authoritative sources. It specifies the domain (company-financial claims), data sources (SEC EDGAR + XBRL), and output (verdict, extracted form, etc.). This clearly distinguishes it from siblings 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 indicates when to use this tool (for company-financial claims about US public companies) and notes that it replaces multiple sequential calls, suggesting when not to do steps separately. However, it does not explicitly name sibling alternatives or state when-not-to-use scenarios.

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