airquality

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that it calls external LLM APIs (Workers AI free, Anthropic with user's key), explains payment responsibility, and details the return structure. This comprehensive disclosure goes beyond annotations.

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

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

The description is concise (two sentences) and front-loaded with the key action and value. Every sentence provides essential information without redundancy.

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

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

For a tool with 4 parameters and no output schema, the description covers the purpose, behavior, return format, and typical use cases. It lacks rate limits or error handling details, but the annotations (openWorldHint) and schema descriptions compensate.

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. The description adds some context (default model for `models`, BYO key for `_apiKey`, disambiguating role of `context`) but does not significantly expand on schema-provided meanings.

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 probes LLMs for visibility scores (0-100) per model, specifies default model and optional Anthropic probing, and lists return fields. This distinguishes it from sibling tools like scan_competitor_ai_presence, which likely focuses on competitive monitoring rather than general brand visibility.

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 contexts: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use or compare to alternatives, but the purpose is clear enough to guide selection.

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

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

With no annotations provided, the description carries full burden and does well by explaining key behavioral traits: it describes the agent's role ('Pipeworx picks the right tool, fills the arguments'), the natural language interface, and the automated tool selection process. It doesn't mention rate limits, authentication needs, or error handling, but provides substantial operational context beyond basic functionality.

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: the first sentence states the core functionality, the second explains the mechanism, the third provides usage guidance, and the fourth gives concrete examples. Every sentence adds value with zero redundancy, making it easy to parse while being information-dense.

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 annotations and no output schema, the description provides excellent context about how the tool works, when to use it, and what to expect. It could be more complete by mentioning response formats or error cases, but given the simplicity of the tool (one natural language input), it covers the essential usage context thoroughly.

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 adds minimal parameter semantics beyond the schema's 'Your question or request in natural language' - it reinforces that questions should be in 'plain English' and provides examples, but doesn't elaborate on constraints, formats, or edge cases for the single parameter.

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

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

The description clearly states the tool'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'), distinguishing it from sibling tools like get_air_quality or get_forecast by emphasizing natural language querying without 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 by indicating this is for natural language queries rather than structured API calls, and includes three concrete examples ('What is the US trade deficit with China?', etc.) that 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?

The description goes beyond annotations by detailing the internal process: resolves market, classifies bet, fans out to relevant packs, and returns comparison. Annotations already indicate read-only and non-destructive behavior, so the description adds procedural context without contradicting annotations.

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

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

The description is front-loaded with the core purpose in the first sentence, then expands on process and usage. It is three sentences plus a marketing note, which is concise but the final sentence ('This is the core demo product...') is less essential. Overall, it earns its keep with minimal 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?

The tool is well-documented given its parameters, annotations, and lack of output schema. The description explains return format (evidence packet + comparison) adequately. It covers input flexibility and internal logic, making it complete for agent invocation without needing to infer missing details.

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?

Both parameters (market, depth) are fully described in the schema. The description adds value by explaining that market can be a slug, URL, or question text, and by giving examples of what depth levels mean ('quick = 2-3 evidence sources'). This enhances understanding 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 states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies supported input types (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). This distinguishes it from sibling tools like ask_pipeworx or entity_profile, which serve different needs.

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: 'Use for "should I bet on X?", "what does the data say about this Polymarket market?", or "is there edge in this bet?".' It also provides a hint that agents using this tool convert better than ones discovering packs themselves, serving as implicit guidance against alternatives.

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

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

No annotations are provided, so the description carries full weight. It discloses data sources (SEC EDGAR for companies, FDA for drugs), return format (paired data + URIs), and the non-destructive nature of comparison. It could be more explicit about read-only behavior or pagination, but the disclosure is sufficient for correct usage.

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, zero wasted words. The first sentence states the core action and range. The second and third provide type-specific details and a benefit statement. Information is front-loaded and easy to scan.

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

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

For a tool with no output schema, the description covers inputs, behavior, outputs ('paired data + URIs'), and rationales. It lacks a detailed structure of the output (e.g., keys in the paired data), but given the simplicity of the tool and the fact that it returns URIs, 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%, baseline 3. The description adds significant value: it maps the 'type' parameter to specific data fields (e.g., type='company' returns revenue, net income, etc.) and gives concrete examples for 'values' (e.g., ['AAPL','MSFT']). This extra context goes beyond 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 the tool compares 2-5 entities side by side, with distinct behavior for 'company' and 'drug' types. It specifies the exact data returned (revenue, net income, etc. for companies; adverse-event reports, FDA approvals, etc. for drugs). This distinguishes it from all sibling tools, which are unrelated (e.g., get_air_quality, 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?

The description provides strong context: it replaces 8-15 sequential calls, implying use when multiple entities need comparison. While it doesn't explicitly list when not to use or alternatives, the sibling list and unique purpose make usage clear. The 'Replaces...' statement is a direct guideline for efficiency.

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 function that returns relevant tools with names and descriptions, and it should be called first in specific contexts. However, it lacks details on rate limits, error handling, or response format, which would be helpful for a tool with no output schema.

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

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

The description is appropriately sized and front-loaded, with two sentences that efficiently convey purpose and usage guidelines without any wasted words. Every sentence earns its place by providing critical information for tool selection.

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

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

Given the tool's complexity (search function with 2 parameters) and the absence of annotations and output schema, the description is mostly complete. It covers purpose, usage context, and high-level behavior, but could benefit from more details on output structure or limitations to fully compensate for the lack of 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?

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 is for tool discovery, but it doesn't provide additional syntax or format details. Baseline 3 is appropriate as 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 resource ('tool catalog'), and explicitly distinguishes it from siblings by emphasizing its role in discovering tools among 500+ available options, which is distinct from the data retrieval functions of get_air_quality and get_forecast.

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 guidelines: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This clearly indicates when to use this tool (for discovery among many tools) versus alternatives, with no ambiguity or misleading information.

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 bears full burden for behavioral disclosure. It details the returned data categories and mentions pipeworx:// citation URIs. However, it does not mention performance, rate limits, or whether results are paginated. Some behavioral aspects are implied but not explicit.

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

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

The description is concise and front-loaded with the purpose. Every sentence adds meaningful information: what data is included, how to identify entities, and when to use an alternative. 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?

Despite no output schema, the description explains the major data fields returned. It also explicitly excludes federal contracts. It could optionally mention defaults like number of recent filings or news articles, but overall it provides sufficient context for the agent to understand the tool's capabilities.

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 covers both parameters with descriptions. The description adds value beyond the schema by clarifying that value can be a ticker or CIK, and that names are not supported. It also reinforces that only 'company' type is supported. Schema coverage is 100%, so baseline is 3; the additional context justifies a 4.

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

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

The description clearly states it retrieves a full profile of an entity across multiple Pipeworx packs with specific data types (SEC filings, XBRL, patents, news, LEI). It distinguishes itself from sibling tools like compare_entities and resolve_entity, and explicitly notes when to use a different tool (usa_recipient_profile for federal contracts).

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

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

The description provides explicit guidance on when to use this tool (comprehensive entity profiling), when not to (federal contracts), and prerequisites (must have ticker or CIK; use resolve_entity for names). This helps the agent decide between this and sibling 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Delete,' which implies a destructive mutation, but doesn't clarify whether deletion is permanent, requires specific permissions, or has side effects (e.g., affecting other tools). For a mutation tool with zero annotation coverage, this is a significant gap in 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 with zero waste. It's front-loaded with the core action ('Delete') and resource ('a stored memory'), making it immediately understandable without unnecessary elaboration.

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

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

Given the tool's complexity (a destructive mutation with no annotations, no output schema, and 1 parameter), the description is incomplete. It lacks details on behavioral traits (e.g., irreversibility, error handling), usage context, or output expectations, which are crucial for safe and effective tool invocation by an AI agent.

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

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

Schema description coverage is 100%, with the parameter 'key' documented as 'Memory key to delete.' The description adds no additional meaning beyond this, such as key format, examples, or constraints. With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

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 unambiguous. It doesn't explicitly differentiate from sibling tools like 'recall' (which likely retrieves memories) or 'remember' (which likely stores them), but the verb 'Delete' strongly implies a destructive operation distinct from those siblings.

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

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

No guidance is provided on when to use this tool versus alternatives. While the description implies it deletes memories, it doesn't specify prerequisites (e.g., whether the key must exist), constraints (e.g., irreversible deletion), or when to choose deletion over other operations with sibling tools like 'recall' or 'remember'.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that it fetches the page, extracts data, and outputs markdown, which aligns with read-only, idempotent behavior. No contradictions. It adds useful context about what the tool does beyond annotations, though it omits potential errors or rate limits.

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

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

The description is a single paragraph of three sentences, front-loaded with the main purpose. No wasted words; every sentence adds value. It is concise and well-structured.

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

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

Given the simplicity (2 params, no output schema, annotations cover safety), the description fully explains what the tool does, the output format, and use cases. It is complete for an agent to select and invoke confidently.

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 both parameters described. The description restates the 'url' parameter with an example and 'max_links' with defaults (already in schema). It adds no additional semantics beyond what the input schema provides, so 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 generates a production-ready llms.txt file for any URL, specifying the action (generate), resource (llms.txt file), and scope (for any URL). It differentiates from sibling tools like ai_visibility_check or ask_pipeworx, which have no overlap.

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: getting a client's site indexed, drafting for own project, or auditing competitor AI visibility. It implicitly tells when to use it, though it does not mention when not to use or direct alternatives. Among siblings, no similar tool exists, so the guidance 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the return values (US AQI, PM2.5, etc.) but doesn't cover important behavioral aspects like rate limits, error conditions, data freshness, or authentication requirements. For a tool with no annotations, this leaves significant gaps in understanding its operation.

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 purpose and required inputs, the second specifies the return values. There's zero wasted text 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 moderate complexity (2 required parameters, no output schema, no annotations), the description provides adequate but incomplete coverage. It explains what the tool does and what it returns, but lacks information about behavioral constraints, error handling, and other operational aspects that would be important for an agent to use it effectively.

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

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

The schema description coverage is 100%, with both parameters (latitude and longitude) clearly documented in the schema. The description doesn't add any additional parameter information beyond what's already in the schema, so it meets the baseline expectation 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 specific action ('Get current air quality conditions') and resource ('for a location'), distinguishing it from the sibling tool 'get_forecast' which presumably provides weather predictions rather than air quality measurements. It specifies the exact data returned, 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 implies usage for obtaining current air quality data at a specific location, but it doesn't explicitly state when to use this tool versus the sibling 'get_forecast' or provide any exclusions or alternatives. The context is clear but lacks explicit guidance on tool selection.

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

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

With no annotations provided, the description carries the full burden. It discloses the return format (hourly data with specific metrics) and implies it's a read-only operation (no destructive hints). However, it lacks details on rate limits, authentication needs, error handling, or data freshness, which are important for a forecast 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?

The description is two concise sentences that are front-loaded with the core purpose and return details. Every sentence earns its place by providing essential information without 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?

Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is reasonably complete. It covers what the tool does and what it returns, but could benefit from more behavioral context (e.g., data source, update frequency) to fully compensate for the lack of annotations and 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?

Schema description coverage is 100%, so the schema already fully documents all parameters (latitude, longitude, days). The description adds no additional parameter semantics beyond what's in the schema, such as explaining coordinate formats or day range implications. Baseline 3 is appropriate when 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 specific action ('Get an hourly air quality forecast'), the resource ('for a location'), and the scope ('hourly' with specific metrics: US AQI, PM2.5, PM10). It distinguishes from the sibling tool 'get_air_quality' by specifying it's a forecast rather than current conditions.

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

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

The description implies usage context by specifying 'forecast' and hourly granularity, which suggests when to use this tool (for future predictions) versus the sibling 'get_air_quality' (likely for current conditions). However, it doesn't explicitly state when not to use it or name alternatives, keeping it at a 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?

With no annotations, the description carries the full burden. It discloses the rate limit (5 messages per identifier per day) and notes it is 'free,' implying no cost. This provides useful behavior context beyond the input schema, though it does not specify if feedback is stored or responded to.

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 long with no wasted words. It front-loads the core purpose and follows with key usage notes and constraints, making it efficient for an agent 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 lack of output schema, the description adequately covers the purpose, parameters, and usage instructions. It explains the optional context object and message format. It does not describe the return value (e.g., confirmation), but for a feedback tool this is acceptable.

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

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

The input schema already has 100% coverage with descriptions for all parameters. The description adds value by elaborating on the enum choices (bug, feature, etc.) and providing the important instruction to not include end-user prompts verbatim, which is absent from 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 is for sending feedback (bug reports, feature requests, missing data, praise) and gives specific instructions on what to include and what not to include. It clearly distinguishes this tool from siblings like ask_pipeworx by targeting feedback rather than queries.

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 when-to-use guidance (bug reports, feature requests, etc.) and explicit instructions on content (describe what you tried, avoid end-user prompts). It also mentions rate limits. While it does not explicitly mention when not to use or alternatives, the context is sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: data is self-aggregating from CF analytics, no PII, and cached 5min-1h depending on window. This goes beyond standard annotations to explain derivation and freshness.

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

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

The description is well-structured with clear sentences separated by line breaks. It front-loads the main purpose, then lists use cases, and ends with derivation details. While slightly longer than a minimal version, every sentence earns its place with no repetition.

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

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

Given low complexity (1 param, no output schema), the description covers all necessary aspects: what it returns, when to use it, how data is derived, and caching behavior. The lack of output schema is mitigated by explicitly stating return fields (top tools, top packs, count).

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 already covers the single parameter 'window' with enum and description (100% coverage). The description adds extra meaning by explaining the trade-off between shorter vs longer windows, which helps the agent decide. Baseline 3 plus slight added 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 returns trending tools/packs and call volume over recent windows. It uses a specific verb ('Returns') and resource ('top tools, top packs, total call volume'), and distinguishes itself from siblings like 'discover_tools' by focusing on trend data derived from other agents' usage.

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 three explicit use cases (discovering hot data sources, confirming canonical tool, aligning with agent needs) and advises on window selection (shorter for hot topics, longer for steady-state). It does not explicitly state when not to use, but the use cases imply appropriate contexts.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, openWorldHint, destructiveHint). It explains the logic (monotonicity violation), the algorithm (walking child markets, extracting dates/thresholds), and the output format. No contradiction with annotations.

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

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

The description is concise and well-structured. It leads with the core purpose, then explains the underlying principle, input, and output, all in a few sentences. Every sentence contributes meaning without unnecessary 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?

The description provides complete context for an agent to decide and use the tool: purpose, reasoning, input format, algorithm summary, and output structure (list of objects with fields). No output schema exists, but the description adequately describes the return format.

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 covers the parameter 'event' with 100% description coverage. The description adds value by providing examples of valid inputs (slug or URL) and clarifying the meaning, which goes beyond the schema's basic type 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 specifies the tool's purpose: finding arbitrage opportunities via monotonicity violations in Polymarket events. It uses a specific verb (find) and resource (arbitrage within Polymarket event), and the detailed explanation with examples distinguishes it from siblings like 'polymarket_edges'.

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 states when to use the tool: when checking for arbitrage from monotonicity violations in a Polymarket event. It instructs the user to pass an event slug or URL. However, it does not explicitly mention when not to use this tool or name alternatives, which would have been helpful.

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

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

Annotations already indicate read-only, open world, and non-destructive behavior. The description adds detailed behavioral info: it groups by asset, fetches price history once, computes model probability, ranks by |edge|, and returns top N with direction. No contradictions.

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

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

The description is concise, well-structured, and front-loaded with the primary action. Every sentence adds value, and there is no extraneous 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 no output schema, the description explains the return type (top N ranked by edge magnitude with trade direction) and covers model assumptions and data sources. It sets expectations about scope (V1, crypto-price bets). Minor omissions like error handling or pagination are acceptable for a simple list 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 description coverage is 100%, so the baseline is 3. The description recontextualizes the parameters (e.g., 'Top N edges to return after ranking') but does not add new meaning beyond the schema 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 scans high-volume Polymarket markets to find where Pipeworx data disagrees with market price, and explicitly targets the 'what should I bet on today' use case. It distinguishes from siblings like 'polymarket_arbitrage' by specifying it covers crypto-price bets and uses a lognormal model.

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

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

The description provides context on when to use the tool (discovering opportunities in crypto-price bets) and its scope (V1, crypto-price bets). However, it does not explicitly compare with alternatives like 'polymarket_arbitrage' or mention when not to use it.

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, destructiveHint false. The description adds detailed behavioral context: it's a data-fetching operation with two modes and explains the return structure (leg prices, spread). 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 comprehensive but slightly lengthy; however, it is well-structured with clear sections and no wasted sentences. The core purpose is front-loaded.

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

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

Even without an output schema, the description fully explains what the tool returns (leg-by-leg prices, spread in pp) and how the modes work. All three parameters are covered, and the behavioral aspects are clear.

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

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

Schema coverage is 100% for all three parameters. The description adds significant value by explaining the interplay between parameters, how topic auto-maps events, and how explicit params override the topic mapping. This goes well beyond the schema 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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving event, distinguishing it from siblings like polymarket_arbitrage by specifying the exact venues and purpose.

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 guidance on two modes (topic vs explicit) with examples, and mentions typical spread range, but does not explicitly state when not to use or list alternatives beyond the sibling list.

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 retrieves or lists memories, works across sessions, and behaves differently based on the 'key' parameter. However, it lacks details on error handling (e.g., what happens if a key doesn't exist), return format, or any limitations (e.g., memory size or persistence). For a tool with no annotations, this is adequate but leaves gaps.

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 sentence states the purpose and parameter logic, and the second provides usage context. Every word earns its place, with no fluff or repetition. It's front-loaded with core functionality, making it easy to parse quickly.

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 (dual behavior based on parameter), no annotations, and no output schema, the description is minimally complete. It covers what the tool does and when to use it, but lacks details on return values, error cases, or system constraints. For a retrieval tool without structured output documentation, this is adequate but not comprehensive.

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

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

The schema description coverage is 100%, with the parameter 'key' fully documented in the schema. The description adds meaningful context beyond the schema: it explains that omitting the key lists all memories, and ties the parameter to retrieving 'previously stored memory.' This enhances understanding without redundancy, justifying a score above the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Retrieve a previously stored memory by key, or list all stored memories (omit key).' It specifies the verb ('retrieve'/'list') and resource ('memory'), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'remember' (which presumably stores memories) or 'forget' (which presumably deletes them), preventing a perfect 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 clear context for when to use the tool: 'Use this to retrieve context you saved earlier in the session or in previous sessions.' It explains the dual behavior (retrieve by key vs. list all) based on parameter presence. While it doesn't explicitly state when NOT to use it or name alternatives (e.g., 'remember' for storage), the guidance is sufficient for effective use.

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

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

No annotations are provided, so the description carries full burden. It describes parallel execution across sources, return structure (structured changes + total_changes count + pipeworx:// URIs), and parameter format. However, it does not explicitly state if the tool is read-only or idempotent, which is acceptable for a retrieval 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?

The description is a single paragraph with multiple sentences, each contributing meaningful information. It front-loads the main purpose and uses examples effectively. It could be slightly more structured but remains efficient and clear.

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

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

Given no output schema, the description adequately covers return values: 'structured changes + total_changes count + pipeworx:// URIs.' It also explains the parallel querying behavior. For a data retrieval tool with three parameters, the description provides sufficient context for an agent to use it correctly.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining accepted formats for 'since' (ISO date or relative), 'value' (ticker or CIK), and the current limitation of 'type' to "company" only. This provides clarity 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: 'What's new about an entity since a given point in time.' It specifies the entity type 'company' and details the fan-out to three distinct sources (SEC EDGAR, GDELT, USPTO), making the tool's specific 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 explicitly mentions use cases: 'Use for "brief me on what happened with X" or change-monitoring workflows.' It also explains the format of the 'since' parameter with examples. While it does not directly contrast with sibling tools, the guidance is sufficient for appropriate 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the persistence differences ('Authenticated users get persistent memory; anonymous sessions last 24 hours') and the scope ('across tool calls'). However, it does not mention potential limitations like storage capacity or rate limits, leaving some gaps.

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, usage, and behavioral details without waste. Every sentence adds value: the first states the core function and use cases, and the second clarifies persistence behavior, making it highly concise and well-structured.

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

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

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is mostly complete. It covers purpose, usage, and key behavioral traits like persistence. However, it lacks details on error conditions or return values, which could be helpful since there's no output schema, leaving minor gaps in 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?

The schema description coverage is 100%, so the schema already documents both parameters ('key' and 'value') with descriptions and examples. The description adds no additional parameter semantics beyond what the schema provides, such as formatting constraints or usage tips, meeting the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose with specific verbs ('store a key-value pair') and resource ('in your session memory'), distinguishing it from siblings like 'recall' (retrieve) and 'forget' (remove). It explicitly mentions what can be stored ('intermediate findings, user preferences, or context across tool calls'), making the purpose unambiguous and distinct.

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 save intermediate findings, user preferences, or context across tool calls'), but does not explicitly state when not to use it or name alternatives. It implies usage scenarios without detailing exclusions or comparing to siblings like 'recall' for retrieval.

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 the tool is a single-call resolver and mentions return fields, but does not explicitly state it is read-only, error handling, or idempotency. The inferred safety is adequate but could be more explicit.

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

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

Two sentences, front-loaded with purpose, followed by specifics. No wasted words.

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

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

Given the simple schema with 2 parameters and no output schema, the description covers inputs, outputs, and scope adequately. It lacks error handling or future version hints, but is sufficient for an agent to use 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 both parameters described. The description adds value by providing concrete examples (AAPL, 0000320193, Apple) and clarifying that 'type' only supports 'company' in v1, which is not in 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 in a single call, specifies the v1 type 'company', and lists accepted inputs (ticker, CIK, name) and outputs (ticker, CIK, name, URIs). It distinguishes from sibling tools like 'ask_pipeworx' and data retrieval tools.

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

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

The description explicitly says 'Replaces 2–3 lookup calls,' indicating when to use it for efficiency. It notes v1 only supports 'company', so usage is constrained. It does not list explicit alternatives among siblings, but the context implies no overlap.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context: it internally calls ai_visibility_check, ranks results, and returns 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?

Description is a short paragraph with a clear front-loaded purpose. Every sentence adds value, though minor redundant phrases exist (e.g., 'surfaces which is most/least recognized' is slightly implied by 'ranks by score'). Still efficient overall.

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 4 parameters, no output schema, and informative annotations, the description is thorough: it explains the internal process, specifies output fields (score, confidence, signal density), and provides a concrete example query. An agent can confidently select and invoke this 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 description coverage is 100%, so baseline is 3. The description goes further by explaining that the first entity in the 'entities' array is treated as the 'subject' for narrative and that the tool probes each entity with ai_visibility_check, 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?

Description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks them, and surfaces most/least recognized. It distinguishes from sibling ai_visibility_check by focusing on multi-entity 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?

Description provides an example use case ('competitive AI-marketing audits') and implies guidance via the phrase 'probes each entity... with ai_visibility_check,' hinting ai_visibility_check is for single entities. However, it does not explicitly state when not to use this tool 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, description carries full burden. It discloses supported claim types, returned verdicts, and that it uses SEC EDGAR+XBRL, but missing details on rate limits, auth requirements, or any side effects. Adequate but not comprehensive.

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, well-structured paragraph front-loads purpose, specifies constraints, and lists output components. Every sentence is informative; 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?

Given simple input (one string) and no output schema, description is largely complete, covering return values and domain. Could mention error handling or unsupported claim types, but not critical for this tool's clarity.

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% (one required param with description). Description adds value by providing concrete examples of valid claims (e.g., Apple's revenue), which clarifies expected format beyond the schema's generic 'natural-language factual claim'.

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 begins with a clear verb ('Fact-check') and specific resource ('natural-language claim against authoritative sources'), immediately distinguishing its function from siblings like ask_pipeworx or compare_entities. It further scopes to company-financial claims, making purpose precise.

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 it replaces 4-6 sequential agent calls, indicating when to use it for efficiency. Domain limitation ('supports company-financial claims') provides context for when not to use, though no explicit 'when-not' alternatives are listed.

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