Waqi

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 valuable context: return format (per-model {score, confidence, signals, raw_response} + combined view), default model, Anthropic's BYO key model (passed straight through), and cost implications. 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 (3-4 sentences), front-loads the main purpose, then details options, return format, and use cases. Every sentence adds 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?

Given the complexity (4 parameters, no output schema), the description effectively covers what the tool does, how it behaves (models, keys), what it returns, and when to use it. The annotations (idempotentHint, readOnlyHint) complement the description for a complete picture.

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 meaning: default model for 'models', only pass '_apiKey' if 'anthropic' in models, and 'context' disambiguates. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It distinguishes from siblings like 'ask_pipeworx' or 'scan_competitor_ai_presence' by focusing on LLM probing for visibility scoring.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to use the default model vs Anthropic, but does not explicitly state when not to use this tool or name alternatives from 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?

The description adds context beyond annotations: it mentions using 3,436 tools across 780 verified sources, routing questions, filling arguments, and returning structured answers with stable citation URIs. No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is well-structured with a bold directive, bullet-like examples, and no wasted words. It is front-loaded with the key instruction ('PREFER OVER WEB SEARCH') and efficiently conveys all necessary information.

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

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

Given the annotations and schema coverage, the description is highly complete. It explains purpose, usage, behavior, and includes diverse examples. 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?

Schema description coverage is 100%, and the schema already explains the parameter and its aliases. The description reinforces this with examples but does not add new semantic depth. However, the examples provide practical guidance, justifying a score above baseline 3.

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

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

The description clearly states the tool's purpose: to answer factual questions about current or historical data using structured sources, with many examples. It distinguishes itself from web search by emphasizing authoritative data and citations.

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

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

Explicitly advises 'PREFER OVER WEB SEARCH' and lists specific scenarios when to use (e.g., 'what is', 'look up', 'current US unemployment rate'). Provides clear guidance on when to choose this tool over alternatives.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and openWorldHint. The description adds value by detailing the exact return structure including refusal reasons and scenarios, complementing the annotations without contradiction.

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

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

The description is front-loaded with purpose, uses bullet points for return structure, and every sentence adds 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?

Given the tool's complexity (hallucination-resistant mode with routing), the description fully explains behavior, return format, failure modes, and usage context. No output schema exists but the description compensates.

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 all aliases documented. The description does not add additional semantics beyond the schema, 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 explicitly states it is a hallucination-resistant answer mode for high-stakes reads, distinguishes from 'ask_pipeworx', and lists specific use cases like financial verdicts and legal claims. The verb 'extracts' clarifies the action.

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 clear when-to-use ('when answer will be quoted, cited, or acted on') and when-not-to-use ('prefer ask_pipeworx for casual lookups'), plus mentions the extra cost (one LLM call).

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 far beyond annotations by explaining the resolution process (resolver contract, market_match_confidence, alternatives), fan-out behavior per classifier, safety mechanisms (low-confidence short-circuits, closed market handling, wide-spread warnings), and the structure of the response. It discloses important traits like how the tool suppresses analysis on low-confidence matches and how it handles de-indexed markets.

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 long and includes many technical details (classifiers, fan-out examples, response shapes, resolver contract) that could be overwhelming. While it is structured with pseudo-headings (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), it lacks conciseness; every sentence is informative but the density may hinder quick parsing.

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

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

Given the complexity of the tool (3 parameters, no output schema, multiple behavioral nuances), the description is exceptionally complete. It covers input formats, processing behavior, response structure, edge cases (closed markets, low confidence, wide spreads), and safety measures. Without an output schema, the description fully informs the agent of what to expect.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing examples for the 'market' parameter and explaining the 'depth' and 'include_raw' parameters in context (e.g., 'quick = 2-3 evidence sources' and the rationale for include_raw). This extra context enriches the agent's understanding beyond the schema.

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

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

The description immediately states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It provides specific examples of use cases and input types, and clearly distinguishes itself from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on researching a single bet comprehensively.

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 the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not directly mention alternatives or when not to use, but the context of sibling tools implies differentiation. The detailed handling of edge cases (closed markets, low confidence) provides indirect guidance on reliability.

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?

Discloses data sources (SEC EDGAR/XBRL, FAERS), handles fiscal year quirks, sorts by primary metric, returns citation URIs. Annotations already indicate read-only, open-world, idempotent behavior, and description adds rich context without contradiction.

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

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

Description is well-structured with trigger phrases upfront, then usage preference, then per-type details. It is slightly verbose but each sentence serves a purpose, making it informative without excess.

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 100% schema coverage and no output schema, the description thoroughly explains what data is returned (financials for companies, adverse events/trials for drugs), sorting behavior, and citation URIs. It addresses all likely agent uncertainties.

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 descriptions already cover both parameters (type enum, values array with constraints). Description adds helpful examples (e.g., ['AAPL','MSFT'], ['ozempic','mounjaro']) and clarifies behavior for each type, providing value beyond schema.

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

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

The description explicitly states the tool compares 2-5 companies or drugs side-by-side, with specific trigger phrases like 'X vs Y' and 'head to head'. It distinguishes from sibling tool 'entity_profile' by recommending preference over sequential lookups.

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

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

The description gives clear when-to-use guidance: for comparing entities, and explicitly prefers over sequential lookups. It also differentiates usage by type ('company' vs 'drug') with specific data sources.

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 context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that each result is callable directly. This goes beyond annotations but still leaves room to detail pagination or result ordering.

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 but includes a long list of example domains that could be trimmed or placed in examples. It is front-loaded with the core purpose, but the list of domains in the middle feels dense and less 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?

There is no output schema, but the description explains the return format (top-N tools with names, descriptions, schemas) and usage guidance ('Call this FIRST'). For a discovery tool with 6 parameters and 100% schema coverage, the description provides sufficient context for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents all parameters (query, q, task, limit, search, description) including aliases. The description does not add new semantic information about parameters beyond what is in the schema, meeting the baseline expectation.

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 a specific verb-resource pair ('Find tools by describing the data or task') and enumerates many example domains (SEC filings, financials, FDA drugs, etc.), clearly distinguishing this tool from siblings that perform specific tasks like 'get_aqi_by_city' or 'validate_claim'.

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 instructs when to use this tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also contrasts with direct-action tools by stating it returns results 'ready to call directly, no second schema lookup needed.'

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?

Discloses behavioral traits beyond annotations: fans out across multiple sources, notes soft-fail for patents due to API sunset, describes fallback mechanism for news (GDELT→GNews), and specifies return structure. 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?

Description is thorough but slightly verbose. It is well-structured with examples first, then core details, but could be trimmed without losing 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?

Despite no output schema, the description comprehensively lists all return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and covers limitations and fallbacks. Fully adequate for an agent to invoke and understand results.

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 both parameters are well-documented. The description adds useful context that names are not supported and that CIK must be zero-padded, but this is largely redundant with 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?

Description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides example queries and distinguishes from sibling tools like resolve_entity by specifying that names are not supported.

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 says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Gives clear guidance on when to use resolve_entity first if only a name is available, and notes input limitations.

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 include destructiveHint: true, which the description supports with 'Delete'. It adds context about memory deletion use cases, but no additional behavioral details beyond what annotations imply.

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?

Extremely concise: three sentences with no fluff. First sentence states purpose, second gives usage guidance, third references related tools. Front-loaded efficiently.

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 delete operation with one parameter and no output schema, the description fully covers purpose, usage, and related tools. No gaps given the tool's simplicity.

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

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

Schema coverage is 100% for the single parameter 'key', which the description only refers to generically. No additional meaning beyond the schema description 'Memory key to delete'.

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

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

The description clearly states the action (Delete) and the resource (previously stored memory by key). It distinguishes from sibling tools 'remember' and 'recall' by mentioning them directly.

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 provides when to use: context is stale, task done, or clearing sensitive data. Also suggests pairing with remember and recall, providing clear guidance on 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?

Describes fetching, extraction, and output format. Annotations already indicate read-only, idempotent, non-destructive; description adds meaningful behavioral detail 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?

Concise two sentences plus a list; no redundancy, front-loaded with main purpose.

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

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

Covers input, process, and output clearly. No output schema, but description explains 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%; description does not add new meaning beyond defaults and max for max_links. Adequate but baseline score.

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 it generates an llms.txt file for URL indexing by AI crawlers. Distinguishes from siblings like 'scan_competitor_ai_presence' which focuses on scanning rather than file generation.

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

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

Explicitly lists three use cases (client indexing, drafting, competitor auditing) and implies input is a URL. Lacks explicit when-not-to-use 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not repeat safety traits. It adds no further behavioral context (e.g., freshness of data, caching, error handling). The description is consistent 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?

One concise sentence that immediately states the tool's purpose and lists key outputs. Efficient but could slightly improve front-loading by stating the action first.

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

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

Given the tool has only one parameter, rich annotations, and an output schema, the description fully covers what the tool returns (AQI, pollutants, weather, station info). No gaps for this complexity level.

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% and the 'city' parameter has a clear description with examples. The description does not add additional semantic meaning beyond what the schema already 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?

Description uses specific verb 'Returns' and resource 'AQI for a city', and lists detailed output fields. It distinguishes from sibling tools like 'get_aqi_by_location' and 'get_aqi_by_station' by specifying 'for a city'.

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 on when to use this tool vs alternatives (e.g., get_aqi_by_location or get_aqi_by_station). Missing when-not-to-use and context about city name format requirements beyond the schema example.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds real-time aspect and nearest-station logic, which is useful context beyond annotations.

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

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

Single sentence, no wasted words, front-loaded with key information. Perfectly concise for the tool's simplicity.

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

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

Given the simple input (2 params) and annotations covering behavior, the description is adequate. It could mention that output is a single station's AQI, but the context of 'nearest' implies one result. Output schema exists but not evaluated.

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

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

Schema coverage is 100% with descriptions 'Latitude' and 'Longitude'. Description adds that these are used to find the nearest WAQI station, providing extra meaning beyond schema.

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

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

Description clearly states 'Real-time AQI for the WAQI station nearest a lat/lon', specifying verb (get), resource (AQI), and scope (nearest station to lat/lon). Distinguishes from siblings like get_aqi_by_city and get_aqi_by_station.

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 explicit when-to-use or when-not-to-use guidance. However, the lat/lon input implies use for location-based queries, and siblings provide alternative input methods (city, station ID). Could mention alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds 'Real-time' indicating live data, but does not disclose error handling, rate limits, or authentication requirements. With good annotation coverage, the additional behavioral context is minimal.

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, front-loaded sentence with zero waste. It includes the key elements: real-time nature, resource (AQI), scope (specific station), and identifier type (numeric UID).

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 presence of an output schema and the tool's simplicity (one required parameter), the description covers the core purpose and identifier source. It could briefly mention that the output contains AQI data, but this is likely covered by the output schema. The real-time aspect is noted, but no details on data range or units.

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 schema description for station_id is informative ('WAQI station UID (returned by search_stations)'). The description only repeats 'by UID (numeric)', adding no new semantics beyond the schema, meeting the baseline for a well-documented 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 retrieves real-time AQI for a specific WAQI station by numeric UID. It distinguishes itself from sibling tools like get_aqi_by_city and get_aqi_by_location by specifying the unique identifier (UID) and referencing search_stations in the parameter description.

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 does not explicitly state when to use this over alternatives. The parameter description mentions 'returned by search_stations', implying a typical workflow, but no direct guidance on when to prefer this tool over others (e.g., get_aqi_by_city).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by specifying the returned fields and the default behavior (active only), which augments the annotations with practical details.

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

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

Two sentences achieve full purpose: first defines action and return fields, second gives usage guidance. No wasted words, front-loaded with 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?

Without an output schema, the description compensates by listing the return fields. With one simple parameter and no nested objects, the description is complete for agent invocation.

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

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

The schema has 100% coverage with one boolean parameter described. The description adds context by stating it lists 'active subscriptions' and mentioning the parameter implicitly for including inactive ones, enhancing the schema's meaning.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on review and providing ids for cancellation.

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 suggests using the tool to 'review what you're monitoring before adding more or to find an id to cancel,' which implies when to use it and contrasts with sibling tools. It could be more explicit about when not to use, but the guidance is clear.

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

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

Annotations provide minimal behavioral info (not read-only, not idempotent, not destructive). Description adds key context: rate-limited to 5 per identifier per day, free, doesn't count against quota. Clearly a mutation 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?

Well-structured: purpose first, then conditions, then tips. Every sentence is informative. No repetition 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 no output schema, the description fully covers input semantics, usage guidance, and behavioral constraints (rate limits, quota). Complete for a feedback submission 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%, but description adds value by explaining the 'type' enum in detail and giving usage guidance for 'message' (describe in terms of Pipeworx tools/packs, no end-user prompt). Also explains the optional 'context' structure.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific categories (bug, feature, data_gap, praise) and distinguishes from sibling tools, none of which are feedback-related.

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: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also provides 'don't' (paste end-user prompt) and rate-limit info.

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 show readOnly, idempotent, non-destructive. Description adds caching (5min-1h), data source (CF analytics-engine), and privacy (no PII), exceeding annotation value.

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?

Concise, front-loaded with core functionality. Three sentences plus bulleted uses. 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?

For a simple tool (1 param, no output schema), description fully covers output, use cases, caching, and data derivation. No gaps.

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

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

Schema has 100% coverage with description for window param. Description adds semantic nuance: shorter windows for hot trends, longer for steady-state, but schema already covers basic meaning.

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

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

Description clearly states action: returns top tools, top packs, and total call volume for a time window. Distinguishes from siblings like discover_tools and ask_pipeworx by focusing on trending analytics.

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 use cases provided: hot data sources, confirming canonical tool, aligning with agent needs. No explicit non-usage guidance, 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?

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds significant behavioral context: requires at least one argument, walks child markets, computes partition checks with threshold, applies Jaccard similarity and partition filters, and describes the response structure. It does not mention potential rate limits or performance, but the added detail is substantial.

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

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

The description is verbose and contains some redundancy (e.g., repeating mode descriptions found in schema). While it front-loads the requirement and uses structured headers, it could be trimmed for conciseness without losing essential guidance.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers inputs, constraints (semantic anchor, partition filter), algorithms, and the response structure including fields like gap_pp, suggested_trade, and reasoning. It is complete for an agent to understand usage and outcomes.

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 provides clear descriptions for both parameters (event and topic) with 100% coverage. The description adds internal algorithm details but does not significantly enhance parameter understanding beyond the schema. Baseline 3 is appropriate since 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 it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, and distinguishes between single-event and cross-event modes. It differentiates from sibling tools like 'polymarket_edges' and 'polymarket_kalshi_spread' by its specific focus on 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 provides detailed internal guidance on when to use 'event' vs 'topic' modes, but it does not explicitly compare this tool to sibling tools or provide when-not-to-use guidance. Usage is implied rather than explicit about 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?

The description provides extensive behavioral context beyond annotations: it details caching (1h KV-level), output structure with segments and diagnostics, edge calculation with slippage and 24h-move warnings, and knob filters. This explains how the tool behaves in ways annotations (readOnly, idempotent) alone do not.

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 very long and dense, mixing high-level purpose with detailed model formulas. It is structured into segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and front-loaded with purpose, but could be trimmed to improve readability without losing 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?

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains caching, output structure (by_segment, fed_candidates, _diagnostics), and edge cases like Fed bets and empty segment diagnostics. The lack of an output schema is compensated by detailed description of response fields.

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 extra meaning for several parameters, e.g., explaining that min_partition_leg_kelly addresses a limitation (partition arbs return kelly_fraction_half=0) and that slippage_pp should be adjusted for thin partitions. However, not all parameters gain additional context 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 it scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan' and 'return') and names the resource (Polymarket markets). The tool is distinguished from siblings like polymarket_arbitrage by its focus on disaggregated edges and Pipeworx 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 says it's built for 'what should I bet on today' and explains that agents use it to discover opportunities without paging hundreds of markets. It provides usage context but does not explicitly state when not to use it or compare to sibling tools like polymarket_arbitrage or polymarket_kalshi_spread, which would be 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?

Goes far beyond annotations by detailing compatibility_warning scenarios, temporal alignment, and skipped cross-type/cross-subtype counters. No contradictions with annotations (readOnlyHint, idempotentHint, etc.). Provides rich behavioral context for safe invocation.

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

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

The description is thorough but verbose (over 200 words). It is well-structured with clear sections, but could be more concise. Some redundancy in explaining compatibility_warning twice. Still, it is front-loaded with core purpose.

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

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

Despite no output schema, the description thoroughly explains the response structure (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, counters). Covers edge cases and provides enough context for an agent to interpret results 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 description adds significant meaning: explains the relationship between topic and explicit parameters, provides example values, and clarifies override behavior. Adds value 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?

Clearly describes the tool as a cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes itself from siblings like polymarket_arbitrage by specifying the cross-venue nature and providing specific modes and safety checks.

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 describes two modes (topic shortcuts and explicit parameters) and provides guidance on when each is appropriate. Includes warnings about compatibility and temporal alignment, helping agents decide when to use the tool. However, lacks explicit comparison to alternatives like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. Description adds scoping to identifier and listing behavior, providing useful context beyond annotations.

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

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

Three sentences, front-loaded with core action. No wasted words, efficient and to the point.

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

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

Given a simple retrieval tool with good annotations and schema, description covers listing, scoping, and pairing. Could mention return value structure but not essential.

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 description for key parameter. Description adds examples of what keys represent (user's target ticker, address, notes), enhancing meaning beyond schema.

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

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

The description clearly states it retrieves saved values or lists all keys, with examples like ticker, address, research notes. It distinguishes from siblings (remember, forget) by name and pairing.

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 says when to use (look up context) and how to list all keys (omit key). Mentions pairing with remember/forget. Lacks explicit when-not-to-use but sufficient for its role.

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: returns specific fields, allows filtering, and includes mark_read feature that flags events as read. 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 3-4 sentences, direct, and front-loaded with the main purpose. Every sentence adds useful 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?

Despite no output schema, the description explains output contents (source, citation_uri, raw payload). It provides usage context (polls, alternative URL) and covers all parameters. Could mention sort order or pagination details, but overall sufficient for the tool's complexity.

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

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

Input schema has 5 parameters with 100% description coverage. The description adds context beyond the schema, such as explaining that mark_read:true makes next call show only newer events and providing example filter values like 'sec_8k'. This adds value to the parameter meaning.

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

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

The description clearly states it pulls fired events from a subscription feed, returns most recent alerts, and lists key fields (source, citation_uri, raw payload). It distinguishes from sibling tools like list_subscriptions by focusing on event retrieval rather than subscription management.

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 polls work fine and provides an alternative URL for scripts/dashboards, giving context on when to use this tool versus other access methods. It lacks explicit when-not-to-use statements but effectively differentiates from siblings.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds details on fan-out to multiple sources, fallback logic, soft-fail for USPTO, and output structure (grouped by source, total_changes count, citation URIs). No contradictions.

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

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

Single dense paragraph front-loads purpose, then details. Every sentence adds unique information (relative date formats, fallback behavior, output summary). No redundant or wasted text.

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

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

Despite no output schema, description covers return format (grouped changes, total count, URIs), multiple data sources, fallback behavior, and limitations. Sufficient for the tool's complexity.

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

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

Schema has 100% coverage with descriptions. Description adds value by explaining relative shorthand for 'since' (e.g., '30d', '3m') and recommending typical monitoring values. Clarifies 'value' accepts ticker or CIK.

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 provides a change feed for a company across SEC EDGAR, news, and USPTO in one parallel call. Explicitly distinguishes from sibling 'entity_profile' by specifying when to use the static profile tool instead.

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?

Offers explicit guidance on when to use this tool (change feed for recent updates) versus when to use 'entity_profile' (static profile). Also explains fallback behavior for news sources (GDELT preferred, GNews fallback) and notes limitations like USPTO API sunset.

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?

Description adds behavioral context beyond annotations: persistence differences (authenticated vs anonymous), scoping by identifier, and storage duration (24h for anonymous). Annotations already indicate idempotentHint=true and non-destructive, and the description aligns without contradiction.

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

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

Description is efficient, providing purpose, usage, and behavior in a few sentences. It is front-loaded with the core action. Slightly verbose for a simple tool but still 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 simplicity (2 required params, no output schema), the description covers the essential aspects: what, when, and how it works. It mentions pairing with siblings, which is helpful. 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 coverage is 100% with descriptions for both parameters. The description adds usage examples but no additional format or constraints beyond what the schema provides. 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?

Description clearly states the tool saves data for reuse, with specific verb+resource (save data). It distinguishes from siblings (recall, forget) by explicitly mentioning them. Examples of use cases (resolved ticker, target address) add concreteness.

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 clear when-to-use guidance: 'discover something worth carrying forward'. It also suggests pairing with recall and forget. No explicit when-not-to-use, but 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 indicate read-only, idempotent, non-destructive. Description adds behavioral details: input formats (ticker, CIK, name for company; brand/generic for drug), return fields (ticker, CIK, company_name; RxCUI, ingredient, brand), citation URIs, and auto-disambiguation. 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?

Approximately 120 words, well-structured with examples and supported types listed. Efficiently communicates purpose, usage, and return values without redundancy. Could be slightly more concise but overall good.

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 two-parameter tool with full schema coverage and annotations, the description provides comprehensive context: how each parameter is used, what is returned (including citation URIs), and the internal multi-step process. No output schema needed as returns are described.

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

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

Schema coverage is 100% with descriptions. The description adds extra meaning: for 'type' lists supported entities with return details; for 'value' gives examples and clarifies that for company it accepts ticker, CIK, or company name with auto-disambiguation.

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 user-spoken names to canonical identifiers required by other tools, with specific examples like ticker, CIK, RxCUI. It uses a specific verb 'resolve' and resource 'canonical/official identifier', and distinguishes from siblings by positioning as the first stop for name-to-ID 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?

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Provides example queries and mentions internal cascading replaces multiple lookups. Lacks explicit when-not-to-use 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds value by explaining it probes each entity with ai_visibility_check and returns a ranked list with 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 concise sentences: purpose, process, and example. No wasted words; front-loaded with the key action. Every sentence earns its place.

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

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

Explains the tool calls ai_visibility_check per entity, outputs ranked list with metrics, and gives a use case. Lacks mention of parameter constraints (e.g., 2-8 entities) but schema covers that. Good overall.

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 per-parameter details beyond what the schema provides; it only gives an overall usage example. No extra value for parameter semantics.

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

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

Clearly states the tool compares AI visibility across multiple entities side-by-side, uses specific verb 'compare' and resource 'AI visibility', and distinguishes from sibling ai_visibility_check (single entity) by mentioning multiple entities and ranking.

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 a concrete use case: 'does Claude know about us as well as our competitors?' and mentions competitive AI-marketing audits. However, it does not explicitly contrast with sibling tools like compare_entities or state 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?

The description adds value beyond annotations by detailing partial failure behavior: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' It also explains the composite nature and what each source contributes, exceeding the idempotent and read-only hints already provided.

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 information-dense yet clear, with no wasted words. It could be slightly more structured (e.g., bullet points), but the front-loading of purpose and usage, followed by behavior and return format, makes it effective.

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

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

Given the complexity (two data sources, partial failures, no output schema), the description covers all essential aspects: return structure (summary block, per-advisory detail, links, alternative versions), ecosystem scope, version default, and graceful degradation. No gaps remain.

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

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

With 100% schema coverage, the baseline is 3, but the description adds context: 'Scoped packages (e.g. "@types/node") are accepted' and 'Defaults to the latest published version when omitted.' This enhances understanding 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 defines the tool as a composite check for npm packages, combining deps.dev and bundlephobia data. The verb 'scan' and resource 'dependency' are specific, and it distinguishes itself from siblings by focusing on npm package evaluation, unlike other tools like entity_profile or search_within.

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 guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also states the NPM-only scope and directs users to deps.dev for other ecosystems (PyPI, Maven, Cargo, Go), clearly indicating when not to use this tool.

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. Description adds return fields but no further behavioral context (e.g., result limit, data freshness). Adequate but not enhanced beyond annotations.

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

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

Two sentences, front-loaded with purpose, then return details. No extraneous words. 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?

For a simple search tool with one parameter, rich annotations, and existing output schema, the description fully covers what is needed. No gaps apparent.

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

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

Description clarifies that keyword should be a city or region name, adding semantic meaning beyond the schema's generic 'Search keyword'. Examples further reinforce this. With 100% schema coverage, description adds significant 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?

Description clearly states verb 'search' and resource 'stations' with scope 'by keyword (city/region name)'. It also specifies return fields. Implicitly differentiates from sibling tools like get_aqi_by_station which require exact identifiers.

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?

Implies usage when searching by city/region name, but does not explicitly state when to use alternatives like get_aqi_by_station or get_aqi_by_location. No exclusions or prerequisites mentioned.

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 (readOnly, idempotent, etc.), the description discloses the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and a 200K character cap with truncation flagging. This adds significant 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 concise (roughly 4 sentences) and front-loaded with the core idea. Every sentence adds unique information: purpose, usage case, technical details, and pairing. No wasted words.

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

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

Given the tool's simplicity (3 params, no output schema), the description covers all necessary aspects: input, output, constraints, algorithm, and integration hints. It is fully complete for an AI agent to decide when and how to use it.

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

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

Schema coverage is 100%, but description adds value by explaining the purpose of each parameter in context: 'Pass the text you already pulled' for 'text', 'natural-language query' with examples for 'query', and 'top-N passages' for 'limit'. It clarifies why each parameter matters.

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 this tool performs semantic search inside a fetched record, returning top-N passages with character offsets and similarity scores. It distinguishes itself from sibling tools like ask_pipeworx_grounded by focusing on local search over already-fetched text.

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: when the record is too large for the prompt. It also provides pairing guidance with ask_pipeworx_grounded, and gives examples of queries. It implicitly states when not to use (if the document is small enough for the prompt).

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?

Description adds significant behavioral context beyond annotations: authentication requirements, type-specific details, delivery channels and limits (10 SMS/day). Annotations indicate idempotent and non-destructive, but description elaborates on side effects and constraints.

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

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

Front-loaded with main action and key requirement. Each sentence adds value, but length could be reduced slightly. Still well-structured and 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 complexity (3 params, nested objects, 4 types, delivery options) and no output schema, description covers all essential aspects: purpose, prerequisites, types, parameters, delivery details, and limitations. Complete for informed usage.

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 description adds concrete examples for each type and explains delivery constraints (e.g., SMS cap, phone verification). Enhances understanding beyond raw 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 verb 'Create' and resource 'subscription' with specific action 'proactive monitoring subscription to a live-data event stream'. Distinguishes from sibling tools like list_subscriptions, unsubscribe, recent_alerts by its creation and monitoring 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 clear context: requires Pipeworx OAuth account, supported types, delivery options. Does not explicitly state when not to use or compare to alternatives, but context is sufficient given 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?

The description discloses that rows are deactivated (not deleted) and ownership is enforced, adding value beyond annotations. No contradictions with annotations (idempotentHint, destructiveHint).

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, no waste. Front-loaded with action, every sentence adds 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?

Given the tool's simplicity (1 parameter, no output schema), the description covers deactivation behavior, ownership, and relationship to recent_alerts, making it complete.

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

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

Schema coverage is 100% with a clear description for 'id'. Description adds 'by id' but doesn't meaningfully extend schema information; 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 action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description provides clear context on when to use (cancel own subscription by id) and explains ownership enforcement. It doesn't explicitly state when not to use, 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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds rich behavioral detail: returns verdict types (confirmed, refuted, etc.), structured form, actual value with citation, and percent delta. It also specifies the data source (SEC EDGAR + XBRL) and scope (public US companies). No contradictions.

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

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

The description is a single paragraph but efficiently front-loads trigger phrases and key info. Every sentence adds value, though it could be slightly more structured (e.g., bullet points) for readability. It remains concise given the information conveyed.

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

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

Despite no output schema, the description thoroughly covers what the tool returns (verdict list, structured form, citation, delta). It explains the tool's efficiency improvement over multiple calls and mentions supported data sources. For a one-parameter tool with comprehensive annotations, this description is complete.

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

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

The single required parameter 'claim' has a schema description with examples, and the tool description provides further context on the type of claims supported (company-financial). With 100% schema coverage, baseline is 3; the description adds value by clarifying expected input format and domain.

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 performs natural-language claim verification against authoritative sources, specifically company-financial claims. It provides trigger phrases and distinguishes itself by consolidating 4-6 sequential calls into a single tool, unlike sibling tools such as 'bet_research' or 'compare_entities' which serve different purposes.

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

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

The description explicitly says to use it whenever the agent needs to check factual correctness of a user statement, and specifies supported domain (company-financial claims). It does not explicitly mention when not to use or name alternative siblings, but the context is clear enough.

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