Waqi

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

Annotations already mark it as read-only and non-destructive; the description adds valuable behavior: the default model choice, the BYO-key billing flow for Anthropic, and the shape of the returned data. This goes beyond the annotations and informs the agent of cost/auth implications, though rate limits or failure modes are not disclosed.

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

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

Three sentences front-load the core purpose, then detail models/cost, then the return structure and use cases. No filler; every clause adds information.

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

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

Without an output schema, the description compensates by itemizing the per-model response object and combined view, and covers default behavior, optional auth, and example use cases. That's sufficient for an agent to select and invoke the tool correctly for its complexity.

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

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

Input schema has 100% coverage with detailed parameter descriptions (e.g., supported models, API key format, context purpose). The description adds perfunctory cost notes but largely repeats what the schema already states, so it provides little extra meaning beyond the structured definitions.

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 specific verb ('Probe') and resource ('one or more LLMs'), defines the scoring range (0-100 per model), and lists concrete use cases. This clearly differentiates it from sibling research tools like bet_research or deep_research, which lack the per-model visibility scoring focus.

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') that establish when this tool is appropriate. However, it does not name alternative tools or state when not to use it, despite siblings like scan_competitor_ai_presence that likely overlap. This prevents a 5 but earns a 4 for clear contextual guidance.

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

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

The description adds substantial behavioral context beyond annotations: it discloses that the tool routes to 5,358 tools, fills arguments, returns stable citation URIs, works on every tier, and makes one fast call. Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior, and the description complements rather than contradicts them.

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?

Despite being relatively long, the description is well-structured and front-loaded with the most important instruction ('PREFER OVER WEB SEARCH'). Each section—usage examples, step-up alternatives, and default behavior—earns its place without redundancy. The formatting with block caps and examples aids scannability.

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 is complete for a tool with no output schema: it explains what return format to expect (structured answer with citation URIs), when to use it, and how it differs from siblings. It also covers edge cases like breaking news and provides examples covering multiple domains. Combined with rich annotations, the tool is fully contextualized.

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

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

The schema covers all six parameters with descriptions, but they are all aliases for the same semantic concept. The description adds valuable clarification that 'question' is the primary parameter and accepts q, query, prompt, text, and input as aliases, which simplifies parameter understanding beyond what the schema alone provides.

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

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

The description clearly states the tool's purpose: answering factual questions about current or historical data by routing to specialized tools and returning structured answers with citations. It distinguishes itself from siblings by explicitly naming alternatives like ask_pipeworx_grounded and deep_research, making the tool's specific role clear.

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, such as 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', plus concrete examples of appropriate queries. It also provides exclusion criteria by explaining when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistance, deep_research for broad multi-part questions), making the usage context fully explicit.

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 adds critical behavioral context: candidate routing improvements are enabled live, no candidate is active right now so it matches ask_pipeworx exactly, and results are compared against the stable router for merge decisions. It also confirms this is a full working router, not a fallback.

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 earning its place. It is front-loaded with the key beta equivalence and current state, then adds usage and fallback clarification. 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?

The description covers purpose, experimental status, current behavior, usage guidance, and fallback. The response shape is referenced as identical to ask_pipeworx, which is sufficient given the simple schema and annotations.

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 documented, including aliases). The description adds no parameter-specific details beyond the schema, so the 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 it is a beta version of ask_pipeworx, an identical universal router with the same 5,358 tools, arguments, and response shape. It distinguishes itself from the stable sibling by noting it is the experimental edge with candidate routing improvements.

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 tells when to use it ('when you want the newest routing') and that it currently matches ask_pipeworx exactly. It also mentions the stable alternative (ask_pipeworx) but does not provide explicit when-not-to-use scenarios.

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

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

Annotations already state read-only, idempotent, non-destructive, open-world, but the description adds substantial non-redundant behavioral details: exact return shape, refusal reasons with enumerated values, extraction constraint ('ONLY what the tool result contains'), and the explicit refusal behavior rather than hallucination. 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, front-loading the purpose, then presenting success/refusal response formats, then usage guidance and cost tradeoff. Every sentence contributes essential information; 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?

Despite lacking an output schema, the description specifies the exact return format and all refusal reason codes, covers routing, source scale, extraction logic, and cost tradeoff. For a moderately complex tool, this is thorough and self-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?

Input schema provides 100% coverage with descriptions for all aliases (question, q, text, input, query, prompt). The description adds no parameter-specific details beyond schema, so the baseline of 3 is appropriate; it does not compensate with extra semantic meaning.

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

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

The description clearly identifies a specific mode ('hallucination-resistant answer mode') with a precise function (extracting answers using ONLY tool result content) and explicitly contrasts it with ask_pipeworx, establishing a distinct resource/scope. It is not a tautology and differentiates 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?

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also mentions the cost tradeoff (one extra LLM call), giving clear when-to-use/when-not-to-use 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 annotations are limited to readOnly/openWorld/idempotent/destructive hints, which the description fully respects and vastly supplements. It discloses concrete behavioral traits: resolution confidence levels ('market_match_confidence ∈ {high, medium, low, none}', 'market_match_score'), safety short-circuiting ('status:"low_confidence_match"'), closed-market handling ('status:"market_closed_or_inactive"'), wide-spread market notes ('tradeability:"illiquid_wide_spread"'), cancellation-rule parsing ('refund_50_50', etc.), news fallback behavior ('_fallback_attempted', 'retry_after_sec'), and response-shape details. This goes far beyond the annotation 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 long but intentionally structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). The opening sentence immediately states the tool's purpose. While verbose, every section adds essential behavioral detail for such a complex tool, and the structure aids scannability. It is well-organized but could be trimmed somewhat without harming clarity.

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

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

There is no output schema, so the description must fully explain return values and side effects, and it does. It details result.market, result.analysis, result.evidence, resolver contract fields, parent_event extraction, news fallback fields, safety statuses, and cancellation-rule impact. It also covers edge cases (low-confidence match, closed markets, wide spreads) and provides concrete examples for many classifier categories. For a tool of this complexity, the description is essentially complete.

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

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

The input schema has 100% description coverage, including detailed descriptions for market (slug/URL/question text), depth (quick/thorough with defaults), and include_raw (with size implications). The tool description also reiterates the market input formats and provides fan-out examples, but it does not add further semantic detail beyond the schema for parameters themselves. Since the schema already does the heavy lifting, the baseline of 3 is appropriate.

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

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

The description starts with a specific verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clarifies the input forms (slug, URL, question text), the internal flow (resolve, classify, fan out, compare), and the intended use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). This clearly distinguishes it from siblings like polymarket_edges or compare_entities by focusing on per-bet evidence 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?

The description gives explicit usage triggers: 'Use for should I bet on X...' and explains the classification and fan-out behavior for various bet types. It does not explicitly exclude alternatives or compare to sibling tools, but it provides enough context (e.g., fan-out examples, resolver contract) that an agent can infer when to use it. Missing explicit 'when not to use' or named alternatives, so not 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?

The description goes well beyond the annotations by disclosing external data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling, sorting by primary metric, and the return format with citation URIs. No contradiction with the readOnly/openWorld/idempotent 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?

Every sentence earns its place: trigger phrases, constraints, data sources, fiscal-year nuance, sorting, output, and efficiency all contribute. The description is front-loaded with user intents and stays dense without becoming wordy.

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 covers return structure, data fields, sorting, and entity constraints. For a 2-param tool with rich annotations, this is fully sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning by specifying exactly what data each type returns (revenue/net income for companies, adverse-event/trial counts for drugs) and giving concrete value examples. This exceeds schema-level 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 specifies a side-by-side comparison tool for 2–5 companies or drugs in one call, with explicit trigger phrases and data sources per type. It clearly distinguishes itself from single-entity tools like entity_profile by emphasizing parallel comparison over sequential lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a clear when-to-use directive and naming the alternative approach to avoid. The 2–5 entity constraint and examples also help the agent decide when this tool is appropriate.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses account/payment requirements, the non-open-web nature, the gaps[] behavior (never invented), the second-hop iteration logic per depth, the hop and citation_uri fields, contradictions[] for standard/thorough, semantic excerpting rather than head-truncation, and latency expectations. This is comprehensive.

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

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

The description is long but each clause adds substantive information: account requirements, data sources, tool routing, output format, usage alternatives, depth behaviors, and performance. It is front-loaded with the sign-in warning and primary use case. The density makes it less scannable than a bulleted list, but no sentence is wasted.

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 specifies the return packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers failure modes (empty gaps for news topics) and performance expectations, making it complete for a complex research 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?

The schema already describes both parameters at 100% coverage, but the description adds contextual meaning: example questions for 'question', and for 'depth' it explains the facet counts (quick=3, standard=5, thorough=8), the gap-recovery and lead-chasing behavior, the contradictions[] scan, and the paid plan requirement for thorough. This goes beyond mere schema enumeration.

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 'Grounded multi-source research across Pipeworx's 1395 STRUCTURED data sources' and explicitly distinguishes it from open-web search and from ask_pipeworx for single lookups. It also specifies the decomposition into facets and parallel routing across 5,358 tools, making 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 explicitly says 'Best for broad/multi-part questions over structured data' and gives direct alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also explains when to choose each depth tier ('quick', 'standard', 'thorough').

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable context about the return format: 'names, descriptions, and full input schemas (with curated examples)' and the convenience that 'each result is ready to call directly, no second schema lookup needed.' This goes 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?

The description is front-loaded with the core purpose and organizes information into clear segments: scope, return behavior, and usage recommendation. The long domain list is informative but somewhat verbose; overall every sentence contributes, but it could be tightened.

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?

Since there is no output schema, the description compensates by explaining the return value in detail: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' Combined with clear usage guidance and annotation coverage, the tool is fully self-explanatory.

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 provides 100% coverage with descriptions for all six parameters, including aliases for query. The description's mention of 'top-N' alludes to the limit parameter but adds no new semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Find tools by describing the data or task') and identifies the resource (available tools across many named domains). It distinguishes itself from sibling tools by positioning itself as the discovery meta-tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

The description provides explicit use cases: 'Use when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST' when exploring many options. However, it does not mention when not to use it or name alternative tools, so it stops short of full exclusion/alternative guidance.

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

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

The description discloses several behavioral traits beyond the annotations: parallel fan-out across sources, exact return fields and URIs, USPTO PatentsView sunset with soft-fail behavior, and a GDELT→GNews fallback. These details add meaningful context that annotations (readOnly, openWorld, idempotent, non-destructive) do not cover, with no contradictions.

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

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

The description is dense but front-loaded with user intents and the core purpose. While it is one long paragraph, every sentence carries useful information about sources, return fields, or constraints. It could be more scannable with line breaks, but it remains concise for the complexity it covers.

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 takes full responsibility for explaining return values, and it does so thoroughly: listing each returned field, limits (up to 5 filings), formats, source fallbacks, and failure modes. Combined with the rich annotation set and clear usage guidance, the description is complete for an AI agent to select 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?

The input schema already provides 100% coverage with descriptions for both parameters, including examples ('AAPL', '0000320193') and the note that names are not supported. The description adds little beyond restating these examples, so the baseline of 3 is appropriate; it does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool's function: it creates a 'full cross-source profile of a US public company in ONE parallel call.' It is specific about the verb (profile), the resource (US public company), and scope (cross-source), and distinguishes itself from siblings like compare_entities and deep_research by its holistic one-call nature.

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

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

Explicit guidance is given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use it (names not supported) and points to the alternative 'resolve_entity first if you only have a name.' This directly addresses when to use the tool vs. 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 destructiveHint=true and readOnlyHint=false. The description adds usage context ('clear sensitive data') but does not disclose additional behavioral traits such as behavior on missing keys or irreversibility, which would be valuable. No contradiction is present.

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

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

The description is three concise sentences: purpose, usage guidance, and tool relationship. Every sentence adds value without redundancy, and the most critical information 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?

For a single-parameter deletion tool, the description covers purpose, when to use, and related tools. It does not mention return values or edge cases, but the tool is simple enough that this is not a major gap.

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% for the 'key' parameter, and the description does not add semantic detail beyond 'by key'. The baseline of 3 applies as the schema already documents the parameter fully.

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 specific verb ('Delete'), resource ('memory'), and scope ('by key'). It clearly identifies the tool as the deletion counterpart to 'remember' and 'recall', distinguishing it from related 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?

It provides explicit when-to-use contexts ('context is stale, task done, clear sensitive data'), and mentions pairing with remember and recall. It lacks an explicit when-not-to-use statement, but the guidance is clear and actionable.

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

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

The description adds behavioral detail beyond the annotations by explaining it fetches the page, extracts metadata, and emits a text blob in llms.txt format. This aligns with the readOnlyHint and openWorldHint, and nothing contradicts the 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 three sentences and front-loaded with the primary purpose. It includes just enough detail on process, output, and use cases without fluff. Every sentence contributes 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?

With only two parameters, strong annotations, and no output schema, the description covers all necessary context: what it does, how it works, what it returns, and when to use it. It is sufficiently complete for an agent to invoke correctly.

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

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

The schema description coverage is 100%, so the parameters are already well-documented. The description does not add extra meaning beyond the schema, such as clarifying the max_links default or usage behavior, but no additional information is strictly necessary.

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

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

The description clearly states the verb and resource: 'Generate a production-ready llms.txt file for any URL.' It specifies the process (fetches page, extracts title/description/key links) and the output format, clearly distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description provides explicit use cases: client sites, personal projects, competitor auditing. It does not explicitly mention when not to use it or name alternatives, but the context is clear enough for an agent to select it appropriately.

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 non-destructive nature. The description adds value by specifying that the data is real-time and detailing the exact return fields (pollutants, weather, station info), which goes beyond the annotations. It does not disclose limitations like city-matching behavior or error handling, but the annotations lower the bar for safety-related transparency.

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

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

The description is a single sentence that front-loads the core purpose ('Real-time AQI for a city') and then efficiently lists required outputs. Every element earns its place, no redundant or filler content.

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

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

Given the simple read-only nature, one parameter, rich annotations, and an output schema, the description is largely complete. It lists all key return fields. However, it omits any caveats such as city name normalization or fallback behavior if a city isn't found, which would make it fully comprehensive. Still, for this complexity level, it's nearly complete.

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

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

The schema has full coverage (100%) for the single 'city' parameter, including an example and format hint. The description adds no additional parameter semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the resource (real-time AQI for a city) and lists specific outputs (AQI value, dominant pollutant, individual pollutant readings, weather, station info). It distinguishes from siblings like get_aqi_by_location and get_aqi_by_station by explicitly focusing on city-level granularity.

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?

Usage is implied: use this tool when you have a city name. However, the description provides no explicit when-to-use or when-not-to-use guidance, and doesn't reference alternative tools like get_aqi_by_location or get_aqi_by_station. Clear context but no exclusions or alternatives, leaving some ambiguity for an AI agent deciding between 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=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds value by specifying 'Real-time' and 'nearest' behavior, giving context about data freshness and station selection logic. 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 a single, front-loaded sentence that conveys the essential information without any filler. Every word is useful, making it highly concise and well-structured.

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

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

This is a simple two-parameter tool with an output schema present, so the description does not need to explain return values. It sufficiently covers the tool's behavior for practical use, though it omits potential edge cases like 'no station found,' which is acceptable for this complexity level.

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

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

The input schema has 100% coverage with descriptions ('Latitude' and 'Longitude'), so the baseline is 3. The description only mentions 'lat/lon' without adding extra details like units or ranges. It does not meaningfully enhance the schema's minimal parameter 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 provides real-time AQI from the WAQI station nearest a given lat/lon. This specifies the verb (get AQI), the resource (WAQI station), and the selection mechanism (nearest to coordinates), which distinguishes it from sibling tools like get_aqi_by_city and get_aqi_by_station.

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

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

The description implies usage when a user has latitude and longitude coordinates, but it does not explicitly mention alternatives or when not to use this tool. Sibling tools exist for city and station queries, but the description does not reference them, leaving the choice to the agent's inference.

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 cover read-only, idempotent, and non-destructive traits. The description adds value by disclosing 'Real-time' behavior (data may change) and the external source 'WAQI', which are not present in annotations. No contradiction found.

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

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

The description is a single, front-loaded sentence that conveys purpose, scope, and selection method. Every word earns its place with no redundancy or filler.

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 one-parameter read-only tool with a complete output schema and rich annotations, the description is quite sufficient. It could optionally mention the need for prior search_stations, but that is already in the parameter description. Overall, the context is complete for the tool's complexity.

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

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

Schema description coverage is 100%, with the parameter description already explaining 'WAQI station UID (returned by search_stations)'. The tool description adds only 'numeric', which is already captured by the schema type 'number'. Thus, the description does not significantly enrich parameter meaning.

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

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

The description 'Real-time AQI for a specific WAQI station by UID (numeric)' clearly states the action (get AQI), the resource (specific station), and the selection method (numeric UID). It distinguishes from siblings like get_aqi_by_city and get_aqi_by_location by emphasizing station UID.

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

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

The description implies when to use this tool (when you have a station UID) and the parameter description explicitly states the UID is returned by search_stations, providing a clear prerequisite. However, it does not explicitly name 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 already convey read-only, idempotent, and non-destructive behavior. The description adds value by specifying the scope ('the caller's') and enumerating the exact fields returned, giving the agent a concrete expectation of the output. It also implies the default only returns active subscriptions, which the schema clarifies with the include_inactive parameter.

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 purpose, followed by return fields and usage guidance. Every sentence serves a distinct purpose with no redundancy or filler.

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 list tool with one optional parameter and no output schema, the description is sufficiently complete: it covers purpose, scope, return fields, and recommended usage. The schema handles the parameter behavior, and annotations handle safety. A minor gap is that the default inactive exclusion is not mentioned in the description, but the schema covers it.

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

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

The input schema fully documents the optional include_inactive parameter (100% coverage), so the description does not need to add parameter details. The description does not mention the parameter, but it adds context about return fields, which is not directly tied to the parameter. Baseline 3 is appropriate given the 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 uses a specific verb+resource construction ('List the caller's active subscriptions') and defines what is returned (id, type, params, created_at, last_fired_at, fire_count). It clearly distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

The description provides clear context for when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies appropriate use cases relative to subscribe/unsubscribe, though it does not explicitly name alternatives or provide exclusion criteria.

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

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

With no helpful annotations (all false or neutral), the description carries the full burden and exceeds it. It reveals that human team members read digests daily, feedback influences the roadmap, there is a rate limit of 5 per identifier per day, and the call is free/doesn't count against quota. This is far beyond the minimal safety disclosure.

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 one tightly crafted paragraph with every sentence contributing: purpose, use cases, content guidance, and operational constraints. It is front-loaded with the main purpose and avoids any fluff or repetition of schema details.

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 feedback tool with no output schema and only three parameters, the description fully accounts for purpose, use cases, content expectations, rate limits, and impact. Nothing important is left ambiguous, making it self-sufficient for correct invocation.

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

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

The schema already describes all parameters at 100% coverage, so the baseline is 3. The description adds actionable guidance beyond the schema, such as describing the issue 'in terms of Pipeworx tools/packs' and not pasting the end-user's prompt. This improves the quality of the message content beyond what the schema alone specifies.

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 specific verb-resource pairing: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools by framing it as a feedback channel for the Pipeworx platform itself, not a research or data retrieval 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?

Explicitly enumerates when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides exclusions, such as not pasting the end-user's prompt, which guides appropriate content.

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 meaningful context beyond this: 'derived from CF analytics-engine, no PII, just (pack, tool, count)', caching behavior ('Cached 5min-1h depending on window'), and the self-aggregating nature. This enriches the agent's understanding of data provenance and freshness.

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

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

The description is concise and well-structured: a clear opening sentence, a list of specific use cases, and a final note on data provenance and caching. Every sentence contributes, with no filler. The use of numbered bullet-like points enhances 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?

Given the simple single-parameter schema and no output schema, the description fully covers needed context: purpose, use cases, return content ('top tools, top packs, and total call volume'), data source, privacy, and caching. The agent can confidently select and invoke this tool based on the description alone.

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

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

Schema coverage is 100% and the schema description already explains the window parameter, including defaults and trade-offs between shorter and longer windows. The tool description only repeats the window values ('24h, 7d, or 30d') without adding substantial new meaning, so it adds marginal value 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 what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It identifies the specific resource (Pipeworx trending data) and the action (returns aggregated usage stats), distinguishing it from sibling tools like discover_tools or recent_changes.

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: 'Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice... (3) seeing whether your use case aligns with what most agents need.' This gives clear context for when to use it, though it does not explicitly name alternatives 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?

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description goes well beyond them. It explains how the partition_check sums YES prices, the >3pp threshold, the semantic anchor (Jaccard ≥0.30), placeholder filtering (>20% returns null), and the fill_check with explicit warning: 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' This provides rich behavioral context not present in 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 well-organized with clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with a concise summary. Every sentence adds value for such a complex tool, though it could be trimmed slightly without losing critical safety warnings.

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

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

For a tool with two optional params and no output schema, this description is remarkably complete. It specifies the response shape (opportunities[], partition_check{...}), edge cases (placeholders, thin legs), expected behavior in cross-event mode, and how to interpret results. The reference to polymarket_fill_risk fills any remaining gaps.

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

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

While the schema already describes both parameters (event and topic) with 100% coverage, the description adds substantial semantics: event slugs examples ('fed-decision-may-2026'), full URL acceptance, topic seed question examples, and what each mode does under the hood. This goes far beyond the schema's basic 'string' definition.

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 specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes the tool from siblings like polymarket_edges and polymarket_fill_risk by naming its exact methodology and output type.

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 explains when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)', and even directs users to a sibling: 'For custom sizing use polymarket_fill_risk.' It also clarifies the no-arg default behavior (trending_scan), giving complete when-to-use guidance.

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

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

The description goes far beyond the annotations (readOnly, idempotent) by disclosing detailed behavioral traits: the three response segments and their model families, the Kelly capping at 0.25, the 24h-move warning, the 'placeholder-slug filter' and partition skip logic, diagnostics funnel counters, and caching behavior ('Cached 1h at the KV level keyed on all knobs'). It also reveals the limitation of Fed bets and why they are excluded, adding meaningful transparency for an agent.

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 and logically organized, front-loaded with the core purpose and then detailing the three segments, knobs, and response structure. Every sentence contributes substantive information, and the use of numbered lists and explicit segment names improves scannability. While it is long, the complexity of the tool justifies the length; but it is not as concise as a two-sentence ideal, so a 4 is appropriate.

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 9 parameters, no output schema, and complex internal logic, the description is remarkably complete. It explains the response top-level shape (by_segment, fed_candidates, _diagnostics), the tradeability filters, the edge calculation, the Kelly caps, and the rationale for exclusions. An agent would have an excellent mental model of what the tool returns and how knobs affect output, with minimal open questions.

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

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

With 100% schema coverage, the baseline is 3, but the description adds substantial value beyond the schema. For example, it explains why min_kelly exists ('Skips opportunities that are too small to bet sensibly'), the practical meaning of slippage_pp ('Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade'), and details the min_partition_leg_kelly interaction with partition arbs. This enriches the raw parameter definitions with context that directly informs invocation decisions.

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 specific verb-resource-scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly defines the tool's purpose and distinguishes it from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx-derived signals and opportunity discovery. The phrase 'Built for "what should I bet on today"' further clarifies the intended use case.

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 the tool ('what should I bet on today' discovery) and includes practical guidance for setting knobs, such as 'Set to 2 to require tight books' and 'Set to 5000 to drop thin-book opportunities'. However, it does not explicitly contrast this tool with sibling tools (e.g., when to use polymarket_arbitrage instead), leaving some differentiation implicit. The strong usage context makes it nearly excellent.

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, non-destructive), the description reveals critical behavioral details: 60-day snapshot TTL, cache-miss snapshot writes, gaps meaning no scan, and decay computed from daily closes rather than intraday. This gives the agent deep expectations about data availability and meaning.

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 every sentence earns its place. It is organized into purpose, args, RESPONSE, and LIMITS, with no redundancy or fluff. The density of information is appropriate given the tool's complexity and lack of output schema.

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?

Since there is no output schema, the description thoroughly defines the response structure (tracked[], expired[], snapshot_dates[]) and explains limitations like TTL and data gaps. It fully prepares the 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?

Both parameters have schema descriptions with 100% coverage, so the baseline is 3. The description restates defaults and adds 'snapshot family' context, but does not introduce new syntax or meaning beyond what the schema already provides.

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

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

The description clearly states the tool's purpose as edge persistence and decay telemetry built from daily polymarket_edges snapshots. It specifically answers the question 'how long has this edge existed and is it shrinking?' and distinguishes itself from the sibling polymarket_edges by focusing on time-series behavior.

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

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

The description provides a clear use case: deciding whether an edge is fresh or stale ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name alternatives or exclusions, but the context strongly implies this tool is for persistence analysis rather than current-edge lookup.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds ladder-walking behavior, return-field semantics, and partial-fill/unhedged-directional-risk disclosure. It does not contradict annotations, so full credit.

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 structured with REQUIRES/SINGLE-MARKET/BASKET labels and no filler. Every sentence adds operational or risk detail, making the length justified.

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 enumerates all return values for both modes, including verdict values, per-leg detail, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also covers prerequisites and failure mode.

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?

Though schema coverage is 100%, the description goes far beyond by explaining the market/event mode split, side defaults, size_usd interpretation per mode, and clamping range. This materially improves click-level understanding.

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

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

The opening phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth' names a specific action and resource. It clearly differentiates from sibling tools by referencing polymarket_arbitrage and polymarket_edges in the usage directive and describes two distinct modes.

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 instructs 'USE THIS before acting on any polymarket_arbitrage...' and specifies a $500 threshold. It explains why partial basket fills are dangerous, giving clear contextual boundaries.

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 declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial behavioral detail: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype explanations, and the fact that most pre-mapped topics return warnings. This discloses internal decision logic and edge cases far beyond annotation hints, with 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 lengthy (over 200 words) but well-structured: lead with purpose, then modes, response, safety, and caveats. Every section carries necessary information for a complex tool with two modes and many edge cases. It is slightly dense and could benefit from bullet points, but the front-loaded purpose and logical flow save it from being disorganized.

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 must fully explain return values, and it does: leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It also covers input modes, overrides, and failure semantics. For a tool of this complexity, the description is complete and leaves no major gap.

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

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

The schema already describes all three parameters with 100% coverage, including examples for topic values and explicit ticker/slug formats. The description adds valuable semantics about how the modes interact: that explicit parameters override the topic-mapped side, and that topic shortcuts auto-fetch matching events. This elevates the meaning beyond the schema, though the schema does heavy lifting, so a 4 is fitting.

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 specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly defines the tool's scope and differentiates from likely siblings like polymarket_arbitrage by focusing on the cross-venue comparison and even explains the two usage modes (topic vs explicit), making 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 provides explicit when-to-use and when-not-to-use guidance. It states that the delta is a real signal only when bet shapes are equivalent, and explains the two compatibility_warning scenarios where 'no arb exists.' It also warns 'pre-mapped ≠ tradeable,' telling users not to assume all shortcuts are usable. This goes beyond simple context by naming exclusions and failure modes.

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 signal read-only, idempotent, and non-destructive behavior, but the description adds essential context beyond that: the dual retrieve/list modes, the scoping to the caller's identifier (anonymous IP, BYO key hash, or account ID), and the lifecycle pairing with remember/forget. No contradiction with annotations exists.

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 compact and front-loaded: the first sentence states the core verb and modes, the second clarifies use cases with examples, and the third adds scoping and lifecycle context. Every sentence earns its place with no redundancy or filler.

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 one optional parameter, strong annotations, and no output schema, the description covers the operation modes, usage context, scoping behavior, and sibling relationships. The return value (the value or key list) is implied by 'retrieve a value' and 'list all saved keys', providing sufficient information for an agent to select 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?

The schema describes the key parameter as optional and to omit for listing, so the baseline is 3. The description adds meaningful semantic context by giving concrete examples of what keys represent (ticker, address, notes) and explicitly coupling key omission to the list-all mode, enriching understanding beyond the schema's terse 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 opens with a precise verb and resource — retrieving a saved value or listing all saved keys — and explicitly distinguishes itself from the sibling tools remember and forget by naming them and their corresponding actions. It provides concrete examples of stored content (user's target ticker, address, research notes), making the tool's purpose unambiguous.

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

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

The description clearly states when to use recall: to look up context previously saved by the agent without re-deriving it from scratch. It also references the companion tools remember and forget, but it does not explicitly name alternative retrieval tools or state when not to use recall, so it stops short of fully explicit exclusion criteria.

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 reveals that setting mark_read:true flags events as read, altering subsequent calls — a behavioral nuance not captured by the readOnlyHint annotation (which is true but conditional). It also adds context about the persisted feed and polling suitability, going beyond the annotations without contradicting them.

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 purpose, and packs in essential details (payload, filters, mark_read side effect, alternative endpoint) without any fluff. Every clause 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 no output schema, the description compensates by listing the returned fields (source, citation_uri, raw event payload) and explaining filtering and mark_read semantics. It also mentions polling behavior and a REST alternative. It does not describe limit defaults or unread_only interactions, but those are already in the schema, so the description is sufficiently complete for a 5-param 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?

The schema already covers all 5 parameters with descriptions (100% coverage), so the baseline is 3. The description adds semantic value by giving a concrete type example ('sec_8k'), explaining the effect of mark_read ('flag returned events read so the next call only shows newer ones'), and noting the default behavior. This enhances parameter understanding beyond the schema.

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

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

The description opens with 'Pull fired events from your subscription feed,' which is a specific verb+resource pair. It further clarifies the source (evaluator-written persisted feed), the payload contents (source, citation_uri, raw event payload), and provides filtering examples, distinguishing it from siblings like recent_changes.

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

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

The description states 'Polls work fine' and offers an alternative endpoint for scripts/dashboards, giving clear usage context for interactive polling versus programmatic access. It also explains filter usage and mark_read behavior, but it does not explicitly compare against sibling tools (e.g., list_subscriptions) or state when not to use this tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive, open-world behavior. The description adds valuable behavioral details beyond annotations: it fans out to multiple sources in one parallel call, discloses the PatentsView API sunset causing soft-failure, explains fallback logic, and describes the return shape (changes[], total_changes, 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?

The description is longer than minimal but every sentence carries functional value. It opens with concrete query examples, then efficiently covers sources, fallback, parameters, and output in a dense, well-structured paragraph. No filler or redundant restatement.

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 the return format (changes[] grouped by source, total_changes count, citation URIs). It covers the complex multi-source fan-out, fallback behavior, parameter formats, and explicitly differentiates from the sibling tool. The description is complete for a tool of this complexity.

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

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

Schema covers 100% of parameters, but description adds meaningful semantics: `since` examples include both ISO and relative shorthand with recommended values ('30d' or '1m'), `value` explains ticker vs. zero-padded CIK, and `type` is clarified as only 'company' supported. This goes well beyond the bare 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 provides a 'change feed' for a company across SEC EDGAR, GDELT/GNews, and USPTO, returning structured changes grouped by source. It includes example natural-language queries and explicitly distinguishes itself from the sibling tool entity_profile, which serves 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?

The description gives rich usage context: when to use (change-oriented questions like 'what happened with X this quarter'), how to specify the window, and explicitly points to entity_profile as the alternative for static profiles. It also notes fallback behavior between GDELT and GNews, which helps set 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?

Beyond annotations (idempotentHint, destructiveHint), the description discloses behavioral traits: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions last 24 hours. This adds significant context beyond the structured data, and there is 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 three sentences, front-loaded with the core purpose, followed by usage guidance and persistence behavior. Every sentence adds value with no redundancy or filler.

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

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

The tool is simple (two required params, no output schema) and the description covers what it does, when to use it, how data is scoped, and how long it persists. It also references sibling tools for complementary operations, making the description complete for an agent to select 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?

The input schema already provides descriptions and examples for both key and value parameters (100% coverage). The description adds examples like 'resolved ticker' and 'target address' but these largely mirror the schema examples. It does not provide additional semantics beyond what the schema defines, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, with a specific verb ('Save') and resource ('data the agent will need to reuse later'). It also distinguishes from sibling tools by mentioning pairing with recall and forget for retrieval/deletion.

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

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

Provides explicit guidance on when to use: 'Use when you discover something worth carrying forward' with concrete examples. It names alternatives (recall for retrieval, forget for deletion), giving clear context on how this tool fits with 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 read-only and idempotent behavior, lowering the bar. The description adds valuable context: it internally cascades through multiple lookup endpoints, auto-disambiguates company inputs, and returns citation URIs. This goes beyond the annotations without contradicting them.

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 well-structured, with example queries at the start, clear sections for supported types, and explicit notes about internal behavior. Every sentence contributes useful information, though it is dense enough that a slightly more compact version could improve scannability.

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 having no output schema, the description fully specifies what each entity type returns (ticker, CIK, company_name, citation URI for companies; RxCUI, ingredient, brand for drugs). It also covers input normalization and the fact that it replaces multiple lookups, making the tool's behavior and expectations complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances the schema by giving concrete examples for the value parameter (e.g., AAPL, 0000320193, 'ozempic') and explaining auto-disambiguation, which adds meaning beyond the raw 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's purpose: resolving a user-spoken name to a canonical/official identifier. It gives concrete example queries, defines supported entity types (company, drug), and specifies the output (ticker, CIK, RxCUI, etc.), making it 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 explicitly directs agents to 'Use FIRST whenever you have a name but need an ID,' which is strong when-to-use guidance. It also details which input forms are accepted for each type, but does not explicitly name alternative tools or state when not to use it, so it falls 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 declare readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds behavioral context by explaining that it 'Probes each entity ... with ai_visibility_check, ranks by score,' and discloses the return format (ranked list with score, confidence, signal density). This goes beyond the annotations by revealing orchestration and output details.

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

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

The description is three sentences, each earning its place: the first explains the core action, the second the method, the third the use case and output. It is front-loaded with the primary purpose and maintains high information density without fluff.

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

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

With no output schema, the description appropriately covers return values ('Returns ranked list with score, confidence, signal density per entity'). It also addresses use case and methodology. It does not mention parameter constraints like the 2-8 entity limit, but those are fully documented in the schema, so the description is complete enough for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'your brand + N competitors' which echoes the schema's note about the first entry being the subject, but it does not add new parameter-level meaning beyond what the schema already provides for entities, models, _apiKey, or context.

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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the resource (AI visibility), the action (compare/probe), and the output (ranked list). It also distinguishes itself from siblings by naming ai_visibility_check, indicating a multi-entity comparison rather than a single check.

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

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

The description provides a clear usage context: 'Useful for competitive AI-marketing audits' with an illustrative example question. It implies that for single-entity checks one would use ai_visibility_check instead, but it does not explicitly state exclusion criteria or alternatives beyond the naming of that sibling tool. This is strong guidance but not fully explicit.

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, idempotent, openWorld), the description reveals critical behavioral traits: partial failures degrade gracefully, with sources_failed listing timeout sources while the rest still returns. It also discloses latency risk (bundlephobia's first measurement can take 5-30s) and the NPM-only v1 constraint, providing context the 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 a single, well-structured paragraph that front-loads the core purpose and then efficiently covers sources, return fields, ecosystem scope, and failure behavior. Every sentence contributes unique information—no filler or repetition—and the length is justified for a composite tool with multiple data sources and edge cases.

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 compensates by explicitly listing the summary block fields and additional return data (per-advisory detail, links, alternative versions). It also covers ecosystem limitations, latency, and partial failure behavior, making it fully self-contained for an agent to understand what the tool returns and how it behaves. The given annotations and parameter schema fill the remaining gaps, so nothing critical 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?

The input schema already provides 100% coverage, describing both package and version parameters with examples and defaults (e.g., scoped packages accepted, version defaults to latest). The description adds no further parameter semantics, so the baseline score of 3 applies; it neither detracts nor enhances the schema's clarity.

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 specific composite purpose—'should I add this npm package to my project' check—and names the exact data sources (deps.dev, bundlephobia) and metrics covered. It clearly distinguishes itself from sibling tools by focusing on npm dependency evaluation. The direct verb 'check' and resource 'npm package' leave no ambiguity.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides an alternative path for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), which functions as a when-not-to-use for this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing the return payload (station UID, name, current AQI, location), helping the agent anticipate what it will receive. No contradictions with annotations.

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

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

The description is a single sentence that is front-loaded with the action, includes the key scope, and mentions the output fields. No wasted words or 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 (one required parameter, comprehensive annotations, and an output schema), the description is complete. It covers what the tool does, what it returns, and the parameter semantics. No significant gaps remain.

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

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

The schema describes the keyword as 'Search keyword' with examples. The description enriches this by clarifying 'city/region name', which adds meaning beyond the schema. With 100% schema coverage, the baseline is 3, but this clarification bumps it to 4.

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

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

The description clearly states the tool searches stations by keyword (city/region name) and specifies the returned fields (UID, name, current AQI, location). This distinguishes it from sibling tools like get_aqi_by_city which likely return aggregated AQI rather than station-level metadata.

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

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

The description implies the tool is for finding stations when a city or region name is known. It provides clear context but does not explicitly state when not to use it or mention alternatives. Sibling tool names suggest there are more direct AQI retrieval tools, but no exclusion is mentioned.

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

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

Annotations already signal a safe read-only operation, and the description adds valuable behavioral context: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K character cap with truncation flag, and the fact that every passage carries an offset for quote verification. These details go far beyond the annotation 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 packed into four dense sentences, each serving a distinct purpose: core function, use-case/benefit, companion-tool relationship, and technical constraints. It is front-loaded with the purpose and contains no filler, making it appropriately concise for the tool's complexity.

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

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

With no output schema, the description adequately covers return structure (passages with offsets and similarity scores) and critical edge behavior (truncation at 200K chars with a flag). It also explains why offsets matter for verification, providing the context an agent needs to trust and use results effectively.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches meaning by defining 'text' as content you 'already pulled' with examples (SEC 10-K body, article), giving example query phrases, and interpreting 'limit' as top-N passages. This adds practical semantics beyond the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record,' and clearly details inputs (text, query) and outputs (top-N passages with character offsets and similarity scores). It differentiates from sibling tools by explicitly positioning itself as the search-within-a-fetched-record tool and naming its companion 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?

It explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt,' and provides an alternative workflow with ask_pipeworx_grounded. This satisfies the when/alternative criteria, giving the agent clear guidance on tool selection.

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

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

The description discloses authentication requirements, phone verification, SMS cap, and the always-on feed behavior. It aligns with annotations (readOnlyHint=false, idempotentHint=true) and adds context such as 'anonymous + BYO cannot persist subscriptions'. This goes beyond the structured annotations.

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

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

The description is moderately sized but well-structured, splitting into types and delivery channels. It front-loads the core purpose before diving into examples, making it scannable. No unnecessary fluff, though some repetition with schema exists.

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 (multiple types, delivery channels, nested objects) and lack of output schema, the description covers the essential behavior: creation, return value, auth, and channel options. It omits webhook details and some type-specific examples, but these are present in the schema.

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

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

The schema already has 100% coverage with detailed descriptions. The description adds practical examples for sec_8k, polymarket_edge, and fred_series parameters, plus clarifies delivery channel constraints like the 10/day SMS cap, enriching the raw schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, returns the new subscription ID, and differentiates from sibling tools like list_subscriptions and unsubscribe by focusing on creation. It is specific with verb+resource and scope.

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

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

The description provides clear usage context: requires a Pipeworx OAuth account, explains supported subscription types with examples, and describes delivery channels. It mentions recent_alerts as an alternative for pulling from the feed, but does not explicitly state when not to use this tool or compare with other creation 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 establish the read-only, open-world, idempotent, non-destructive nature. The description adds valuable behavioral context by describing the return format (category-bucketed examples with exact tool+argument shapes), the live-catalog source, and the no-arguments vs topic argument behavior. It does not mention potential limits, but the added detail goes beyond basic annotation coverage.

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

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

The description is a single dense paragraph, but every clause serves a purpose: user intents, output contents, usage modes, and placement in the workflow. It is longer than ideal but still efficient given the amount of guidance needed for an onboarding tool.

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 adequately explains what is returned and how to use the tool. It covers categories, tool+argument shape, the live catalog, and the optional topic parameter. It is complete for an agent to decide when and how to invoke it, without requiring additional detail.

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 topic parameter, and the schema already provides the full list of focus areas. The description adds examples ('finance', 'pharma', 'betting') but these are redundant with the schema's enumerated values. The description does not introduce new meaning beyond what the schema already conveys.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It is specific about the resource (Pipeworx capabilities) and the action (suggesting questions), and the 'Use this FIRST' guidance distinguishes it from sibling tools like discover_tools or ask_pipeworx.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also provides usage variants: 'Call with no arguments for the full spread, or pass topic to focus'. This gives clear context 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?

The description adds meaningful behavioral context beyond annotations by explaining ownership enforcement and that the row is deactivated, not deleted, preserving history via recent_alerts. This complements the annotations (e.g., idempotentHint, destructiveHint) and gives the agent a clear mental model.

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 action, and every sentence adds value (action, ownership, deactivation semantics). No redundancy or filler.

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 single-parameter tool with rich annotations, the description covers the essential aspects: what it does, side effects (deactivation), and relationship to other tools (recent_alerts). No output schema is needed, and the behavioral context is sufficient.

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

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

The input schema already provides 100% coverage for the single parameter, describing it as 'Subscription id (uuid) returned by subscribe.' The description reinforces this by saying 'by id' but adds no new semantic information 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 a specific action ('Cancel a subscription by id') and identifies the resource (subscriptions). It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on the cancellation operation and its deactivation behavior.

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: it's for canceling your own subscriptions, with ownership enforcement noted. It doesn't explicitly state when not to use or mention alternatives, but the context is unambiguous enough for an agent to select it appropriately.

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 key behavioral details: the SEC EDGAR + XBRL fast path with percent-delta math, the fallthrough to a grounded pipeline with verbatim evidence, and the specific verdict types returned. This adds valuable context not present in the 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 every sentence earns its place: opening with user-phrase examples, stating the use case, explaining the two processing paths, listing the return structure, and highlighting the efficiency gain. It is well-organized and front-loaded with the 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 the tool's complexity and lack of an output schema, the description is remarkably complete. It explains scope (financial vs. other), routing logic, return values (verdict, actual value, citation, reasoning), and replaces sequential calls. No critical context 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?

The schema already provides 100% coverage for both parameters ('claim' and 'tolerance_pct') with clear descriptions. The tool description adds no additional parameter semantics beyond what the schema offers, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with illustrative phrases like "fact check" and "verify the claim that…". It distinguishes itself from siblings by noting it replaces multiple sequential calls and provides a definitive verdict.

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

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

Explicit usage guidance: "Use whenever the agent needs to check whether something a user said is factually correct." It also differentiates between company-financial claims (structured SEC EDGAR path) and all other factual claims (grounded pipeline). No implicity or ambiguity about when to apply it.

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