Openaq

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already indicate safe, non-destructive behavior. The description adds valuable context: it returns the nearest station with most recent pollutant values and other nearby stations, going beyond what annotations provide. No contradiction.

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

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

The description is two sentences, front-loaded with the main action, then usage examples, then what it returns. No unnecessary words; every sentence adds value. Structure is efficient and easy to parse.

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

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

Given 4 parameters (all documented in schema), complete annotations, and no output schema, the description adequately explains what the tool returns (nearest station values and nearby stations). No gaps identified.

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

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

Schema description coverage is 100% (all parameters have descriptions). The tool description does not add meaning beyond the schema, such as format or constraints. Per guidelines, baseline 3 is appropriate when schema fully covers parameters.

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

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

The description clearly states the tool's function: 'Get the latest air-quality readings... at the monitoring station NEAREST to a latitude/longitude.' It specifies the pollutants and indicates it returns multiple stations, making the purpose unambiguous and distinct from sibling tools.

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

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

The description provides explicit usage contexts like 'air quality near me', 'what is the air quality at <coordinates>', and 'is the air bad in <place> right now', guiding when to prefer this tool. It does not explicitly exclude alternative tools but the guidance is clear and 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 declare readOnlyHint, idempotentHint, and destructiveHint as true. The description adds context about the free default model, the BYO key model for Anthropic, and the return format (per-model data + combined view). It does not mention rate limits or failure modes, but the core behavioral traits are well covered.

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 (three sentences) and front-loaded with the main action. Every sentence adds value: the first sentence states purpose and scoring range, the second explains models and cost, the third gives return format and use cases. 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 lack of an output schema, the description provides a clear outline of the return format (per-model score, confidence, signals, raw_response + combined view). All parameters are covered and the use cases are well described. The tool's behavior is fully communicated.

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?

All parameters have schema descriptions, and the description adds further meaning: it explains that `models` can be omitted for just workers-ai, that `_apiKey` is required only if 'anthropic' is in models, and that `context` helps disambiguate. It also describes the return structure in detail.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and returns a visibility score (0-100). It specifies the default model and the option to add Anthropic. This distinguishes it from sibling tools like 'scan_competitor_ai_presence' and 'deep_research' by focusing on 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 indicates when to pass `_apiKey` (to include Anthropic) and defaults to a free model. However, it does not explicitly state when not to use the tool or 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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: it routes to one of 5,578 tools, fills arguments, returns a structured answer with stable pipeworx:// citation URIs, and claims to work on every tier with one fast call. It does not contradict annotations and enriches the agent's understanding of what happens under the hood.

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 longer than average but every sentence earns its place: it starts with a strong directive (PREFER OVER WEB SEARCH), enumerates use cases, gives examples, and clearly distinguishes when to use sibling tools. The structure is logical and front-loaded with the most important guidance, though it could be trimmed slightly without losing essential context.

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 that acts as a gateway to thousands of sources, the description covers the essential context: what it does, when to use it, examples, return format (citations), and alternatives. It also mentions tier compatibility and speed. It lacks details on error handling or cases where no match is found, but given the absence of an output schema, it gives enough for an agent to decide when to invoke it and 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?

The input schema has 100% coverage, thoroughly describing the single required parameter 'question' and its aliases (q, text, input, query, prompt). The description provides many real-world examples of questions but does not add additional parameter-level semantics beyond what the schema already states. Baseline 3 is appropriate because the schema carries the full parameter documentation.

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

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

The description states a clear, specific purpose: route factual questions to the right tool among 5,578 verified sources and return structured answers with citations. It explicitly differentiates itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different needs, and includes concrete examples of questions.

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 when-to-use guidance: 'PREFER OVER WEB SEARCH' for a long list of categories, and it names the exact alternatives to use when a more grounded single answer or broad multi-part research is required. It also clarifies that for breaking-news, this tool already routes to live news sources, removing ambiguity.

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

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

Although annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial context beyond annotations: it explains the beta nature, the candidate routing improvements, that no candidate is active right now (with a specific date), and that results are compared against the stable router. This gives the agent a full picture of the tool's experimental behavior without contradicting the safety hints.

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

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

The description is about 4 sentences and front-loaded with key facts: it's the beta version, identical router, candidate routing is off now. It's fairly concise, though a bit verbose with details about retirement date and comparison strategy. It earns its place, but could be trimmed slightly for focus.

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 and a single required parameter, the description covers the essential context: what it does, how it relates to the stable version (ask_pipeworx), current status, fallback behavior, and intended use. The annotations cover safety traits, so additional behavioral depth is not strictly necessary. It's complete for the tool's purpose.

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

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

Schema description coverage is 100%, and all six parameters are aliases for the same question string. The description doesn't add new parameter semantics, but it does note 'same arguments' and 'same response shape' as ask_pipeworx, which is useful context. Baseline 3 is appropriate since the schema documents the parameters thoroughly and the description adds a small note about identical arguments.

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 'ask' plus resource 'pipeworx' and explicitly frames it as a beta/experimental universal router. It distinguishes itself from the sibling 'ask_pipeworx' by stating it is the beta version with identical tooling but candidate routing improvements live under test, and even notes that currently no candidate is active, so it matches ask_pipeworx exactly.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router to decide what merges. It also mentions there is no fallback and this is a full working router, which sets clear expectations for when 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, and destructiveHint=false. The description adds substantial context: it discloses the exact return format on success and failure, the refusal_reason enum, that it extracts answers ONLY from tool results, and the cost implication. 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 front-loaded with the core purpose, then systematically covers behavior, return format, usage guidance, and cost. Every sentence adds distinct value—no fluff. It is structured logically and remains concise given the complexity.

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

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

For a complex tool with routing, extraction, and multiple refusal modes, the description is remarkably complete. It explains the routing (same as ask_pipeworx), the extraction constraint, the exact return envelopes, when to use it, and why. Even without an output schema, the return structure is explicitly documented.

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 6 parameters (aliases), and the required 'question' parameter has a clear description in the schema. The tool description adds no extra parameter-level meaning beyond restating natural language input. Baseline 3 is appropriate since the schema carries the burden.

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 a distinct purpose: 'hallucination-resistant answer mode for high-stakes reads' and explicitly differentiates from ask_pipeworx by describing the grounded extraction and refusal behavior. It names the verb ('ask') and specifies the resource (Pipeworx) with a clear scope ('high-stakes reads'), distinguishing it from siblings.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and when-to-avoid: 'prefer ask_pipeworx for casual lookups.' It also gives a concrete reason (extra LLM call cost) and names the alternative 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 indicate read-only, idempotent, open-world behavior. Description adds extensive behavioral details: fan-out logic, response shapes (market, analysis, evidence), resolver contract with confidence levels, parent event extraction, news fallback handling, safety mechanisms (low-confidence short-circuit, closed market handling, wide spread warnings), and resolution rule risk. 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 lengthy but well-structured with sections in all caps and clear examples. Front-loaded with purpose. Although dense, every sentence adds value given the tool's complexity. Could be more concise, but the organization aids readability.

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 documents return fields (market data, analysis, evidence, resolver contract, parent event, news fields) and edge cases (low confidence, closed markets, wide spread, cancellation rules). The description alone provides sufficient context for an agent to understand the tool's behavior and output.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The main description adds value by explaining the difference between 'quick' and 'thorough', the effect of 'include_raw', and elaborates on the 'market' parameter input types. While schema descriptions are adequate, the extra context improves 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?

Clearly states it researches a Polymarket bet by pulling Pipeworx data. Specifies input types (slug, URL, question text) and distinguishes from siblings like polymarket_arbitrage or polymarket_edges by focusing on single bet research.

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

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

Explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). Provides classifier examples and fan-out scenarios, helping the agent decide when to invoke this tool. While not directly contrasting siblings, the context strongly implies 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?

Beyond annotations (readOnly, idempotent, openWorld), the description details data sources, fiscal year handling, sorting by primary metric, and citation URIs. 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?

Well-structured with example queries, direct instructions, and data source details in a compact but informative paragraph. Front-loaded with key information.

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

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

Given two parameters and no output schema, the description fully covers functionality, data sources, result interpretation, and return format (paired data + citations). No missing pieces for an agent.

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

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

Schema covers both parameters with descriptions, so baseline is 3. Description adds context about tickers/CIKs, max/min, and fiscal year handling, 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 clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, specifying exact data sources for each type. It distinguishes from siblings like entity_profile and 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives concrete example queries. Provides clear guidance on when 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses critical behaviors: account/paid-tier requirements, 15-60s latency, gaps[] never invented, citation_uri only when fetchable, contradictions[] for standard/thorough, semantic excerpting, and hop fields. This far exceeds the structured data and enriches the agent's understanding of side effects and limitations.

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 but densely packed with essential operational details, structured logically from account requirements to use cases, depth behavior, and output characteristics. While it could be trimmed slightly, every sentence serves a purpose given the tool's complexity.

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

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

For a tool with no output schema, the description thoroughly describes the return packet contents (verbatim evidence, confidence, source, fetched_at, citation), the gaps[] contract, contradictions[], and latency expectations. It also covers edge cases (current news, signed-out users) making it fully adequate for invocation decisions.

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 have detailed descriptions, so the baseline is 3. The description adds extra nuance by noting that depth:'thorough' requires a paid plan and clarifying the trade-offs between quick/standard/thorough in terms of hop behavior and contradiction scanning, which goes beyond the schema's enum 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 it performs 'grounded multi-source research across Pipeworx's 1463 STRUCTURED data sources' in one call, decomposing questions into facets and routing to tools in parallel. It distinguishes itself from open-web search and sibling tools like ask_pipeworx, 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 text gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and clear exclusions ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also specifies the account requirement and fallback if not signed in, providing thorough directional context.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. The description adds context on return format (top-N tools with names, descriptions, schemas, examples) and behavior (ready to call directly), which annotations do not cover.

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

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

The description is informative and front-loaded, but slightly verbose. It efficiently conveys the tool's purpose and usage, though a minor reduction in the list of domains could improve conciseness.

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

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

Despite no output schema, the description fully explains what is returned (top-N tools with schemas and examples) and the primary use case, making it complete for this discovery 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% with detailed parameter descriptions. The description mentions aliases and limit, but these are already in the schema. No significant added meaning beyond the schema.

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

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

The description uses specific verbs 'browse, search, look up, discover' and clearly states the resource 'tools' with a list of domains, distinguishing it from sibling tools that perform specific actions.

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 'Call this FIRST' when exploring many tools, but does not specify when not to use it, e.g., if the desired tool is already known. However, the guidance is clear and 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds value by detailing the multi-source fan-out (SEC, XBRL, USPTO, news, GLEIF), specific return fields, USPTO sunset May 2025 with soft-fail behavior, and generation of pipeworx 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?

While the description is lengthy, every sentence adds value. It front-loads with example queries and then provides a structured breakdown of sources and outputs. Could be slightly more concise, but the density of information justifies the length.

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

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

Despite lacking an output schema, the description thoroughly explains the return structure: cik, company_name, recent_filings (with URIs), fundamentals sorted by date, patents with sunset note, news fallback, and LEI. It covers caveats and limitations (e.g., only US public companies, names not supported). Adequate for a complex tool.

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

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

Schema coverage is 100%. The description goes beyond by clarifying that 'value' can be a ticker or zero-padded CIK, and explicitly states that names are not supported, directing to resolve_entity. This adds practical usage context beyond the schema's 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 explicitly states 'full cross-source profile of a US public company' with example queries like 'Tell me about X' and 'company profile for Microsoft'. It clearly distinguishes itself from sibling tools by recommending it over chaining single-pack 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?

Includes explicit preference instruction: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also specifies when not to use (if only a name, use resolve_entity first), providing clear context for agent decision-making.

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

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

Annotations declare readOnlyHint, idempotentHint, and non-destructive behavior. The description goes beyond by revealing that the tool returns specific fields (station id, name, country, coordinates, pollutants with sensor ids, resolved_place), explains radius defaults (12 km) and max (25 km), and clarifies that location is required for filtering. It does not contradict any 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 four sentences, each serving a distinct purpose: listing search methods, describing return fields, stating usage context, and emphasizing location requirement. It is front-loaded with the core action, uses no filler, and every sentence earns its place. Excellent structure.

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 relative simplicity (read-only query with 8 parameters, no output schema), the description fully covers the necessary information: search methods, return values, parameter details, and usage constraints (requirement for location argument). No gaps are apparent; an agent would have sufficient context to invoke this tool correctly.

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

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

Input schema has 100% description coverage, providing baseline 3. The description adds value by explaining that '_apiKey' is optional (gateway supplies one), that 'city' can include country for ambiguous names, and that 'radius_km' has defaults and max. It also clarifies that 'bbox' expects a specific string format. These details enhance 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 'Find OpenAQ air-quality monitoring stations by location' and enumerates four distinct search methods (city, coordinates+radius, country, bounding box). It also explicitly differentiates this tool from sibling 'get_measurements' by framing it as the first step for historical series, which helps the agent select the correct tool.

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 on when to use this tool: 'first step for a historical series: find the station here, then pass its sensor_id to get_measurements.' It also explicitly states 'At least one location argument is required — the tool will not return an unfiltered global list,' which prevents misuse. However, it does not explicitly mention when not to use it or provide alternatives to sibling tools like 'air_quality_near', though the differentiation is implicit.

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 destructiveHint=true and idempotentHint=true. Description confirms deletion behavior and adds context (sensitive data, stale context) but does not disclose additional behavioral traits 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 with no wasted words. First sentence states action, second gives usage guidance and pairing information.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage guidelines, and relationships with siblings. Complete and sufficient.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter. Description adds 'by key' but does not elaborate on format or constraints 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?

Description clearly states verb 'Delete' and resource 'previously stored memory by key'. Distinguishes from siblings like 'remember' and 'recall', which are for storing and retrieving respectively.

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 usage scenarios: stale context, task done, clear sensitive data. Pairs with 'remember' and 'recall' for context, but does not explicitly 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?

Annotations already indicate safe read operation; description adds specifics: fetches page, extracts title/description/key links, outputs standard markdown format. 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?

Two sentences plus a bulleted list, no redundancy. Purpose is front-loaded and every sentence adds value.

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

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

For a simple tool with two parameters and no output schema, description explains the process and output format sufficiently. All necessary context provided.

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

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

Schema covers both parameters fully (100% coverage). Description only implicitly references URL and max_links, adding no new semantic detail 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?

Clearly states it generates an llms.txt file for a URL, with specific verb and resource. Distinguishes itself from sibling tools which cover different domains.

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

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

Explicitly lists three use cases (client indexing, personal project, competitor audit) providing clear context. No exclusion conditions mentioned but not necessary given unrelated 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 declare readOnlyHint, openWorldHint, and destructiveHint, so the description's role is lighter. It adds value by specifying the return format (parameter, value, units, time), which is beyond the annotations. 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?

Two concise sentences with no filler. The main action and key details are front-loaded. 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?

With an output schema present, the description need not detail return values. It covers input parameters, prerequisites (find_stations), and the overall goal. Complete for a simple read-only 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 the description adds meaning by explaining the location_id originates from find_stations and noting the _apiKey is optional. This exceeds the baseline expectation 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 retrieves the latest reading for every pollutant at a specific OpenAQ station, specifying the resource (pollutant readings) and distinguishing it from siblings like get_measurements which likely returns historical 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 provides clear context on when to use (for latest readings at a station) and directs users to obtain location_id from find_stations. However, it does not explicitly exclude alternative tools or mention when not to 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?

The description adds critical behavioral context beyond annotations: it warns that many sensors are archived and 'most recent' can be years old, and advises checking timestamps. This complements the readOnlyHint and idempotentHint annotations, enhancing the agent's understanding of tool behavior.

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

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

The description is concise (two sentences plus an important note), front-loads the primary purpose, and uses efficient language. Every sentence adds value without unnecessary verbosity.

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, the description does not need to explain return values. It covers what the tool does, how to use it, key caveats (old data), and prerequisites, making it complete for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%, providing clear descriptions for each parameter. The description adds value by explaining that limit controls the number of most recent readings and that sensor_id comes from find_stations. While not exhaustive, it meaningfully supplements 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 retrieves the most recent time series (hourly or daily aggregates) for a single OpenAQ sensor, ordered newest first. It specifies the resource (time series), the verb (get), and the scope (single sensor). This distinguishes it from siblings like get_latest and find_stations.

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 usage for pollutant trends over time at one station/parameter and advises using find_stations or get_latest to select an active sensor. This provides clear context and alternatives, guiding the agent on when and how to apply the 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=true, idempotentHint=true, destructiveHint=false. Description adds return fields but no new behavioral traits beyond what annotations provide.

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. Purpose first, then usage guidance. Information density is high.

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 tool with annotations covering safety and schema covering params, description adds usage context and lists return fields, making it fairly complete. No output schema, but return fields are listed.

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 optional parameter. Description does not add meaning beyond the schema's definition of 'include_inactive'.

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

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

Clear verb 'List' and specific resource 'the caller's active subscriptions'. Distinguishes from sibling tools like subscribe/unsubscribe by listing what's returned.

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

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

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context, though lacks explicit 'when not to use' 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 only mark readOnlyHint=false, destructiveHint=false, etc., which are not informative by themselves. The description adds meaningful behavioral context: filing returns a claim_token, the team reads digests daily, the action is rate-limited to 5 per identifier per day, and it is free and quota-exempt. No contradictions with annotations; the description carries the transparency burden effectively.

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

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

The description is a single dense paragraph but is front-loaded with the core purpose. All sentences add necessary detail (scope, categories, claim_token, rate limits, quota). It is longer than the two-sentence benchmark, but the length is justified by the multi-part behavior it needs to explain, and it remains tightly written without 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?

With no output schema, the description carries the burden of explaining return behavior, which it does via claim_token. It also covers prerequisites (no account needed), rate limiting, scope boundaries, and why feedback matters (roadmap impact). The only minor gap is not explicitly describing the outcome when an account is provided, but the claim_token path is fully specified, making the tool complete enough for effective use.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the claim_token round-trip usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, adding practical semantics that the schema alone does not convey.

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 opens with a clear imperative: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and the action (sending feedback), and distinguishes itself from sibling retrieval/research tools by focusing solely on reporting issues or praise about Pipeworx itself.

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?

It explicitly states when to use ('Use when a tool returns wrong/stale data...'), enumerates the feedback categories, and provides a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is strong when/when-not guidance with no ambiguity, and it also explains how to reuse the claim_token later.

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

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

Annotations already mark readOnly, openWorld, idempotent, non-destructive. The description adds useful behavioral details: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). 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 two sentences, front-loads the core functionality, then provides use cases and technical details. Every sentence adds value with 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?

No output schema, but description explains return values (top tools, packs, volume) and caching. With one optional parameter, this is fairly complete. Could include example output format, but sufficient.

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

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

The one parameter 'window' is fully described in schema (enum values). The description adds semantic value by explaining that shorter windows surface hot trends and longer windows show steady-state demand, aiding selection.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window. It uses specific verbs and distinguishes itself from siblings like 'discover_tools' by focusing on 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 lists three concrete use cases, providing context for when to use. It does not explicitly state when not to use, but the use cases imply appropriate scenarios.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds rich behavioral context: semantic anchor threshold (0.30 Jaccard), partition filter (placeholder fraction >20% returns null), fill check details (theoretical vs realizable edge), and trade-avoidance guidance. 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 dense but well-structured with section headings (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds valuable information. While not extremely concise, the length is justified by the complexity of the tool, and it is front-loaded with the 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?

Given no output schema, 2 parameters with 100% schema coverage, no required params, and sibling list, the description fully compensates by detailing output structure (opportunities[], partition_check) and fill_check behavior. It explains edges, reasoning, and trade suggestions comprehensively.

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 substantial meaning: explains what 'event' expects (slug or URL), what 'topic' expects (seed question), and behavioral implications (semantic anchor, partition filter). It significantly augments 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no args (trending_scan), event mode (single slug), and topic mode (cross-event). This specificity differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Provides when-not-to-use advice via fill_check and recommends polymarket_fill_risk for custom sizing. This matches perfect use-case differentiation.

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 extensively details behavioral traits beyond annotations: three segments with model families, edge calculation methods, slippage, Kelly fractions, diagnostic fields, and 1-hour caching. No contradictions with annotations (readOnlyHint, idempotentHint, 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 thorough and front-loaded with purpose, but it is lengthy. Every sentence adds value and provides necessary detail for correct usage, though some specifics (e.g., alpha values) could be externalized. Overall well-structured for an LLM.

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 (9 parameters, three segments, no output schema), the description is exceptionally complete. It covers segments, calculations, parameter interactions, diagnostics, and caching. Without an output schema, this level of detail is essential and fully 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 description coverage is 100%, so baseline is 3. The description adds extra meaning for parameters like min_partition_leg_kelly, explaining why parent-level Kelly is zero and how per-leg filter works. Some parameters are covered adequately but not enhanced beyond schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement and providing comprehensive opportunity details.

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 this tool (discovering opportunities without paging) and explains segments, parameters for filtering tradeable edges, and that Fed bets are excluded from ranking. It lacks explicit 'when not to use' statements but implicitly differentiates from 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?

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds significant behavioral context: reliance on daily closes, trend computation, snapshot gaps, 60-day TTL, and limits on decay numbers. 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 well-organized: purpose first, then detailed explanation of response fields with clear formatting, followed by limitations. Every sentence adds value, no redundancy.

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

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

With no output schema, the description fully documents return values (tracked, expired, snapshot_dates) with field semantics and edge cases (gaps, trend computation, decay sign convention). Sufficient for agent 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% with clear parameter descriptions. The description adds defaults and clamps (days: default 14, clamp 2-30; window: default '1wk', families listed) and explains how they affect the output (snapshot family selection).

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

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

The description explicitly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge age and decay. This clearly distinguishes it from siblings like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description includes a concrete use case: distinguishing a fresh wide edge from a 3-week-old wide edge, implying when to use this tool. However, it does not explicitly state when not to use it or provide direct comparisons with 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?

The description adds significant behavioral context beyond annotations (readOnlyHint, idempotentHint, destructiveHint). It details internal mechanics (walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, etc.), partial fill risks, and forced directional risk. 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 somewhat long but well-structured: summary line, requirements, then separate sections for single-market and basket, concluding with a usage directive. Every sentence adds value, though minor redundancy could be trimmed. Front-loaded with key info.

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

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

Despite lacking an output schema, the description enumerates return fields and verdicts for both modes, covers edge cases (thin_legs, forced_directional_risk), and explains partition logic. Complete enough for confident tool invocation without external documentation.

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%, baseline 3. The description adds extra meaning: explains that size_usd means 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional' for basket, and clarifies default side logic in basket mode. This exceeds 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 performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing two modes (single-market and basket) and listing specific return fields. It explicitly differentiates from siblings polymarket_arbitrage and polymarket_edges by prescribing when to use this tool.

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 when-to-use guidance: before executing arb signals or trades above ~$500. It warns against partial basket fills converting arb into unhedged directional positions, and explains when not to use (thin books). Mode selection (market vs event) is clearly described with defaults.

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 extensively explains behavioral aspects beyond annotations, such as compatibility_warning conditions, temporal_alignment checks, skipped_cross counters, and the meaning of matched_pairs:0. This far exceeds the basic read-only/idempotent 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 detailed but somewhat lengthy; however, it is well-structured with clear sections and front-loads the core purpose. Some redundancy exists but it's justified given the tool's complexity.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers response fields (leg prices, spread, safety fields) and error conditions. It provides sufficient information 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%, so baseline is 3. The description adds meaning by explaining the two modes, topic shortcuts, and override behavior. However, it does not explicitly state that at least one mode must be specified.

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 identical questions, with specific verb 'spread' and resource 'cross-venue'. It distinguishes from sibling tools like polymarket_arbitrage by being cross-venue.

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 details two usage modes (topic and explicit tickers) and provides guidance on when not to use (e.g., when compatibility_warning fires). It also notes that most pre-mapped topics are not actually tradeable, setting clear expectations.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds scoping, listing behavior, and pairing with siblings. Enhances beyond 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?

Three sentence description: purpose, usage, scoping and sibling pairing. No redundancy, efficient 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?

Complete for a simple retrieval tool with one optional parameter. Covers purpose, usage, scoping, siblings. No output schema but return value is implied.

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 already explains the key parameter (omit to list all). Description reinforces this but adds little new meaning beyond 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 clearly states the tool retrieves a value saved via remember or lists all saved keys if omitted. It explicitly distinguishes from sibling tools remember and forget, fulfilling the specific verb+resource+differentiation criteria.

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

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

Describes when to use (look up context stored earlier) and pairs with remember/forget. Notes scoping to user identifier. No 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond by explaining the mark_read parameter's state-changing behavior ('Flag the returned events read so the next call only shows newer ones'), and notes the same feed is available via GET for external use, adding valuable context.

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

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

The description is concise at five sentences, front-loaded with the main purpose, and each sentence adds value without redundancy. It is well-structured for quick comprehension.

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

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

Despite lacking an output schema, the description explains the return content (source, citation_uri, raw payload), covers all parameters with examples, and addresses common use cases like polling and state management. It is fully adequate for a read tool with 5 parameters.

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

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

Schema coverage is 100%, so parameters are described in the input schema. The description adds meaning by providing an example for 'type' (e.g. 'sec_8k'), specifying 'since' as an ISO timestamp, and explaining the purpose of mark_read, which enriches the parameter semantics 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 starts with 'Pull fired events from your subscription feed,' which is a specific verb+resource. It clearly states the tool's function and distinguishes it from siblings like 'list_subscriptions' or 'recent_changes' by focusing on fired alerts.

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 guidance on when to use the tool ('Polls work fine') and mentions an alternative endpoint for scripts and dashboards. It implies this tool is for interactive or programmatic access, though it doesn't explicitly 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?

Discloses parallel fan-out to SEC EDGAR, GDELT→GNews fallback, and USPTO (with soft-fail note). Explains return structure (changes[] grouped by source, total_changes, citation URIs). Adds 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?

Well-structured with bullet points and clear front-loading of purpose. Slightly verbose but efficiently organized.

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

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

No output schema, but description adequately covers return structure, source behavior, and parameter details. Includes fallback and soft-fail notes, plus alternative tool guidance.

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 usage examples and suggestions (e.g., '30d' for typical monitoring). Provides concrete examples for value and confirms type restriction.

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 provides a change feed for a company using multiple sources in one parallel call. Includes example queries and explicitly distinguishes from sibling entity_profile for static profiles.

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

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

Explicitly says to use this tool for 'what's new' queries and directs to entity_profile for static profiles. Also describes fallback behavior between GDELT and GNews.

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 write operation (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds useful context: scoping by identifier, persistence duration (authenticated vs anonymous), and pairing with recall/forget.

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 (5 sentences) and well-structured: purpose first, then usage, then behavioral details. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (2 required params, no output schema), the description covers purpose, usage, behavior, and pairing with siblings. It is complete for an agent to select and use the tool correctly.

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

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

Schema coverage is 100% with clear descriptions for 'key' and 'value'. The description adds naming conventions (e.g., 'subject_property', 'target_ticker'), providing extra semantic guidance 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: 'Save data the agent will need to reuse later.' It provides specific examples (resolved ticker, target address) and distinguishes from sibling tools 'recall' and 'forget' by naming them explicitly.

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 tells when to use ('when you discover something worth carrying forward') and pairs with recall and forget, providing clear context for when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds substantial behavioral context beyond them: cascading internal lookups ('Each call cascades through several lookup endpoints internally'), graceful degradation when GLEIF/OpenFIGI are unavailable, explicit labeling of unresolved identifiers under `unresolved`, and the ISIN-to-LEI mapping behavior. This is rich, non-contradictory 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 long but every section earns its place: it opens with concrete query examples, states the primary directive, enumerates supported types with precise identifier sources, explains degradation and unresolved handling, and closes with the efficiency benefit. It is well-structured and front-loaded, with no filler or 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?

For a complex two-parameter tool with no output schema, the description is exceptionally complete. It covers input variations, output identifiers per source, cross-source behavior, unresolved handling, URL citations for drugs, graceful degradation, and internal cascading. Nothing critical for agent selection or invocation is missing.

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?

While the schema covers both parameters (`type` and `value`) with descriptions, the tool description greatly expands their semantics: it details accepted input forms for `value` (ticker, CIK, ISIN, or company name for company; brand/generic for drug), explains special cases like ISIN resolving to legal entity, and clarifies `type` values beyond the enum. This adds meaning significantly beyond the schema.

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

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

The description explicitly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides a specific verb (resolve), resource (entities like company/drug), and scope (to official identifiers), and distinguishes from siblings by positioning it as the first step when an ID is needed. The examples like 'ticker for...' and 'find the CIK for...' make the purpose unmistakable.

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 explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the tool cascades through multiple endpoints to replace manual lookups. However, it does not explicitly name alternative sibling tools or state when not to use it beyond the implied ID-need condition, so it stops short of a 5.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. 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?

Single short paragraph, front-loaded with main action and example. Every sentence provides useful information without 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 4 parameters, no output schema, and no nested objects, the description covers the tool's purpose, internal process, and return values (ranked list with score, confidence, signal density). It also provides usage example, making it complete for an agent to select and invoke correctly.

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

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

Schema descriptions cover 100% of parameters. The description adds value by stating the first entity is the 'subject' for narrative, explains models (workers-ai free default, anthropic requires API key), and mentions context disambiguates common names.

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

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

The description clearly states that it compares AI visibility across multiple entities side-by-side, with a specific verb ('Compare') and resource. It differentiates from sibling tools like 'ai_visibility_check' by mentioning it probes each entity with that tool and ranks results.

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: 'Useful for competitive AI-marketing audits' and an example question. Implies when to use (comparing multiple entities) vs. single-entity checks via 'ai_visibility_check', but lacks an explicit when-not guideline.

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 behavioral context beyond annotations: it discloses that bundlephobia's first measurement on a new version can take 5-30 seconds, that partial failures degrade gracefully, and that sources_failed will list timed-out sources. This is valuable for an agent managing timeouts and error handling.

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

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

Single paragraph is densely packed with essential information, all relevant to agent decision-making. No filler or redundancy. Key info 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?

The description fully explains the return value structure (summary block fields, advisory details, links, alternative versions), partial failure behavior, and timing characteristics. No output schema exists, making this thorough coverage essential and well-executed.

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 described. The description adds extra context: version defaults to latest when omitted, and scoped packages like @types/node are accepted. This is helpful beyond the schema's descriptions.

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

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

The description clearly states the tool is a composite check for evaluating whether to add an npm package, combining data from deps.dev and bundlephobia. It distinguishes itself from siblings by being specific to npm packages and providing a unified check for safety, popularity, and size.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, or size of an npm package (e.g., 'what does adding lodash cost me'). Also specifies the ecosystem limitation (NPM only in v1) and mentions alternatives for other ecosystems (deps.dev:version directly).

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

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

Annotations already provide safety hints (readOnlyHint, idempotentHint, destructiveHint). The description adds valuable details: embedding model (BGE-base-en), chunk size (500-char overlapping windows), character cap (200K chars with truncation and flagging), and that every passage includes an offset for verification.

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 (~150 words) and front-loaded with the core purpose. Every sentence adds value, no fluff, and clearly communicates 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?

Despite lacking an output schema, the description fully covers what is returned (passages with offsets and scores), usage context, and technical limits. It provides complete guidance for an AI agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, baseline at 3. The description adds rich context: examples for text (SEC 10-K body, article) and query (supply-chain risk, fiscal year 2024 revenue), plus technical details about embeddings and truncation behavior, significantly enhancing understanding beyond schema.

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

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

The description clearly states the tool performs 'Semantic search INSIDE a fetched record' and specifies inputs (text, query) and outputs (top-N passages with character offsets and similarity scores). It differentiates from siblings by mentioning its specific use case and pairing with 'ask_pipeworx_grounded'.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt' and suggests alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

Annotations indicate idempotentHint=true, readOnlyHint=false, etc. The description adds context: requires OAuth, lists delivery limitations, webhook signing details, and auto-disable behavior. 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 well-structured and packs necessary detail, though slightly long. It starts with purpose then dives into specifics, but some redundancy could be trimmed (e.g., delivery details repeated in param description and delivery block).

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 (3 params, nested objects, no output schema), the description covers types, parameters, delivery options, and prerequisites. However, it does not explain the return value format aside from 'Returns the new subscription id', nor idempotency behavior despite the hint.

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

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

Schema coverage is 100%, but the description adds significant value by explaining type-specific parameters (e.g., sec_8k items codes, polymarket_edge topic) and delivery channel details (e.g., webhook HMAC signing, email validation).

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 creates a proactive monitoring subscription to a live-data event stream and returns a subscription id. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 requirements (Pipeworx OAuth account, no anonymous/BYO), supported types with parameter examples, and delivery channel constraints (SMS cap, webhook auto-disable). It does not directly contrast with sibling tools but implicitly guides 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds that it returns category-bucketed example questions with tool+argument shapes, and mentions live catalog and no-args vs topic behavior. No contradictions; adds meaningful 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?

The description is reasonably concise given the information packed: purpose, examples, output category list, usage context. Every sentence contributes. Could be slightly tightened but overall well-structured and 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?

Given no output schema and one simple parameter, the description fully explains what the tool returns (category-bucketed examples with tool+argument shapes), how to use it (no args vs topic), and when (onboarding). No 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?

Schema coverage is 100% with a single optional parameter. Description enriches by explaining that omitting topic gives full spread, and provides example values (finance, pharma, betting). This adds useful context beyond the bare schema description.

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

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

The description clearly states this is the onboarding entry point for Pipeworx, returning category-bucketed example questions with tool+argument shapes. It distinguishes from sibling tools like discover_tools and ask_pipeworx by being the first tool to use when unsure of capabilities.

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 to use this FIRST when you don't know what Pipeworx can do, and explains how to customize with topic argument vs full spread. References meta-tools (ask_pipeworx, entity_profile, etc.) as what you learn to call, providing clear usage context.

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

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

The description discloses key behavioral traits beyond annotations: ownership enforcement (only cancel own subscriptions), and that the row is deactivated (not deleted) preserving historical events. This complements the annotations (destructiveHint=false, readOnlyHint=false) 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 consists of two concise sentences that front-load the action and then provide constraints and side effects, with 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 with one parameter and no output schema, the description provides sufficient context: the action, ownership, and post-call behavior (deactivation, historical data access via recent_alerts).

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

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

The single parameter 'id' is fully described in the schema (100% coverage) as a subscription UUID returned by subscribe. The description adds minimal extra meaning beyond confirming it is the same id, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions' by noting ownership enforcement and the row being deactivated rather than deleted, with historical events available via 'recent_alerts'.

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 this tool (to cancel your own subscriptions) and mentions that historical events remain available, but does not explicitly exclude alternative tools 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?

Annotations declare readOnlyHint/openWorldHint/idempotentHint, but the description adds critical behavioral nuance: it explains that 'could_not_verify' indicates a check did not happen and must not be treated as evidence, and that 'unsupported' means no source was found. It also discloses the two internal routing paths and the return structure (verdict, actual value, citation, reasoning), going well 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 long but information-dense, with a clear flow: usage triggers → two pipelines → return value → critical caveats → efficiency benefit. Every sentence adds value; even the parenthetical list of verification triggers is useful for NL understanding. The structure prioritizes the most actionable information upfront.

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?

This is a complex tool with multiple verdict types, two processing paths, and special semantic meanings for certain outcomes. The description comprehensively covers all of this, including the exact verdict enum, the presence of a pipeworx:// citation, the warning about 'could_not_verify', and the fact that it replaces multiple sequential calls. With no output schema, the description appropriately shoulders the burden of explaining return semantics.

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 100% coverage of both parameters with clear descriptions, including an example for 'claim' and the tolerance range/behavior for 'tolerance_pct'. The tool description adds a bit of context about tolerance being used for hallucination detection, but it mostly repeats or implies what the schema already states, so it earns the 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 uses specific verbs like 'verify', 'fact check', and 'confirm or refute' to clearly state the tool's purpose: natural-language claim verification against authoritative sources. It distinguishes itself from siblings by describing its tailored fast path for company-financial claims and a grounded pipeline for all other factual claims, plus the explicit note that it replaces 4–6 sequential calls.

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

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

The description explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and provides detailed guidance on the two distinct pathways (SEC EDGAR/XBRL for financial claims, grounded pipeline for anything else). It also frames the tool as a single-call replacement for a multi-step process, giving a clear efficiency rationale.

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