Wmata

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: per-model results structure (score, confidence, signals, raw_response) and that Anthropic calls require a BYO key with direct billing. No contradictions.

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

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

Two sentences with no waste. The first sentence front-loads the core function and output; the second gives practical use cases. Every sentence earns its place.

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

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

For a probing tool with no output schema, the description provides sufficient detail: what it does, default model, optional key, per-model output structure, combined view, and concrete use cases. No gaps.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by stating the default model and clarifying that _apiKey is passed through to Anthropic, going beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for visibility scores (0-100) of a business, brand, product, or topic. It distinguishes from siblings like compare_entities and entity_profile by focusing on LLM knowledge scoring.

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

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

The description gives explicit use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains default model vs optional Anthropic key. However, it does not mention when not to use or compare with similar sibling tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable context about the tool's routing behavior, citation format (pipeworx:// URIs), and that it works on every tier with a single fast call. No contradictions 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 front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and progressively adds detail. While longer than some, every sentence serves a purpose: defining scope, providing examples, and differentiating from siblings. Could be slightly more concise but is well-structured.

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

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

Given the high parameter count (6, all aliases), rich annotations, and no output schema, the description fully compensates by explaining how the tool works internally (routing, citation URIs), when to use it, and when not to. No gaps remain for effective agent decision-making.

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 all 6 parameters (one required, 5 aliases) documented. The description adds value by explaining that the question can be in natural language and that it will be routed to the appropriate tool, which goes beyond what the schema provides. The examples in the schema further clarify usage.

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

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

The description clearly states the tool is a routing agent for factual questions across 5,564 tools and 1,462 verified sources, returning structured answers with citation URIs. It explicitly differentiates itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use them instead.

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

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

The description provides explicit guidance on when to prefer this tool over web search ('PREFER OVER WEB SEARCH'), includes specific use cases and example queries, and clearly states when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions, and break-news handling is already covered).

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds crucial context beyond annotations: that it has candidate routing improvements that may be under test, that no candidate is active currently, that it falls back to nothing (it's a full working router), and that its purpose is comparative evaluation. These details explain the experimental nature and fail-safety, which annotations alone don't convey.

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

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

The description is a single paragraph but packed with essential information: beta identity, relationship to stable router, active status, usage instructions, behavioral expectations. Every sentence serves a purpose with no filler. It front-loads the key fact ('Beta version of ask_pipeworx') immediately.

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 (universal router with ~5,564 tools, no output schema), the description covers purpose, usage, current state, behavioral expectations, and fallback behavior. Annotations already handle safety, so the description fills all remaining gaps. It is fully complete for making an informed invocation decision.

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

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

Schema coverage is 100% with documentation for 'question' and its aliases. The description does not repeat parameter details, which is acceptable given full schema coverage. It adds value by confirming that the argument set is identical to ask_pipeworx (same 5,564 tools, same arguments, same response shape), reinforcing consistency. The baseline of 3 is exceeded by this cross-reference.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with candidate routing improvements. It distinguishes itself from the sibling 'ask_pipeworx' by noting that it is the experimental edge, and specifies that currently it matches exactly due to no active candidate. The verb 'use' plus resource 'ask_pipeworx_beta' with scope 'universal router' makes 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?

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router to decide what merges. It also states that no candidate is active, so it currently matches, preventing confusion about when to pick this over 'ask_pipeworx'. This provides clear when-to-use and behavioral context relative to sibling.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description's job is partially reduced. The description adds significant behavioral context: the tool runs the full 'ask_pipeworx' pipeline but extracts answers from tool results, returns explicit refusal reasons, and costs an extra LLM call. This goes beyond annotations and helps the agent understand the internal mechanism and failure modes.

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 key purpose ('Hallucination-resistant answer mode') and provides a clear, structured definition. Most sentences add value. It could be slightly more concise by trimming the folding of the output format into a single line, but still well within acceptable bounds.

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 (picks from 5,564 tools across 1,462 sources), the description covers purpose, when to use, behavioral traits, parameter aliasing, and failure modes despite no output schema. The return format is described adequately for an agent to parse. Minor gap: the description doesn't explain whether the evidence quote is from the tool result or the final answer, but this is inferred from the mechanism.

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

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

Schema coverage is 100%, with all 6 parameters mapped as aliases for 'question'. The description adds minimal parameter-level detail beyond the schema, stating 'Your question in natural language'. Since the schema already describes the parameters well, the description doesn't need to add much. Baseline 3 is appropriate.

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

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

The description clearly states the tool provides a 'Hallucination-resistant answer mode for high-stakes reads'. It specifies the verb+resource combination: it picks the right tool, fetches data, and extracts answers using only the tool result. It distinctly differentiates itself from ask_pipeworx by describing a grounded, evidence-based output format with explicit refusal reasons.

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

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

The description provides explicit guidance on when to use this tool ('high-stakes reads', 'whenever an answer will be quoted, cited, or acted on') and when to prefer ask_pipeworx ('for casual lookups'). It also explains the cost tradeoff ('one extra LLM call'). However, it doesn't explicitly say when NOT to use it beyond implying ask_pipeworx for casual use, and it doesn't compare directly to other sibling tools like deep_research or validate_claim.

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

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

Annotations already indicate readOnly, openWorld, idempotent. The description adds extensive behavioral details: fan-out parallelism, resolver contract (confidence levels, alternatives), parent event extraction, news fallback mechanisms, safety short-circuits (low-confidence, closed markets), liquidity warnings, and resolution-rule risk. This goes far 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 long but well-structured with headings (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded purpose. Every section adds value, though some agents might find the verbosity slightly excessive for quick lookup.

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

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

Given the tool's complexity and lack of output schema, the description comprehensively covers inputs, fan-out examples, response shapes, resolver contract, parent events, news fields, safety, and resolution rules. It leaves no ambiguity about what the tool does and returns.

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

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

Schema coverage is 100% with good descriptions, but the description adds significant value: explains market input as 'slug, URL, or question text,' clarifies depth options ('quick = 2-3 evidence sources, thorough = full fan-out. Default thorough.'), and include_raw with size implications. Examples further enhance 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 description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It provides specific use cases like 'should I bet on X' and distinguishes from sibling polymarket_* tools by focusing on research rather than trading or arbitrage.

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

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

The description gives explicit usage examples ('Use for "should I bet on X"...') and hints at context (e.g., when you need data on a bet). However, it does not specify when NOT to use it or directly name alternative tools from the sibling list, which would improve cross-tool differentiation.

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

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

Annotations already mark it as readOnlyHint, idempotentHint, non-destructive. The description adds value by specifying the returned data structure (incident description, route IDs, update time, incident type), providing context beyond 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?

One sentence with essential information. It is front-loaded with the purpose and immediately lists what is returned. No wasted words.

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

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

Given no parameters, comprehensive annotations (readOnlyHint, idempotentHint, destructiveHint false), and an output schema, the description adequately captures the tool's behavior and return values. No gaps remain.

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

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

The tool has no parameters, and schema description coverage is 100%. The description does not need to add parameter meaning; baseline is 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 specifies the verb 'fetch', the resource 'WMATA bus service alerts and incidents', and lists returned fields (incident description, affected route IDs, date/time updated, incident type). This clearly distinguishes it from sibling tools like rail_incidents or bus_predictions.

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

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

The description implies usage for fetching current alerts, but does not explicitly state when to use this tool versus alternatives (e.g., rail_incidents for rail alerts). No exclusions or prerequisites are mentioned, which is acceptable given the tool has no parameters and is read-only.

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 readOnly, idempotent, non-destructive. Description adds return fields (route ID, direction, etc.) beyond annotations.

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

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

Two sentences, no fluff, front-loaded with action and output.

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?

Adequate for a simple read-only tool with output schema; lacks error handling or rate limits but not critical.

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?

Only parameter stop_id is mentioned but not described in format or source; schema coverage 0% and description minimally adds 'by stop_id'.

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

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

Description clearly states the tool fetches real-time next-bus arrival predictions by stop_id, distinguishing it from siblings like bus_stops or bus_route_details.

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

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

Implied use case for real-time predictions, but no explicit when-to-use or when-not-to-use compared to alternatives like bus_incidents or rail_predictions.

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, destructiveHint=false, idempotentHint=true. The description adds value by specifying that results include direction names, stop names/IDs, and geo coordinates, which is not in the schema. No contradictions.

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

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

Two efficiently worded sentences with no filler. First sentence states purpose and parameters, second lists output content. Every piece 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?

Given the simple fetch operation with one required parameter and an existing output schema, the description sufficiently covers what the tool does and what it returns (directions, stops, coordinates). No missing context.

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

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

Schema coverage is 0%, but the description mentions both parameters (route_id and date) and clarifies that date is optional. It could provide more details like date format or route_id format, but it adds enough context beyond 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 uses a specific verb 'Fetch' and identifies the resource as 'stop sequence and path details for a WMATA bus route'. It clearly distinguishes from sibling tools like bus_routes and bus_stops by focusing on detailed route info.

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

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

The description implies usage for fetching route details by route_id and optional date, but does not explicitly state when to use or avoid this tool versus alternatives. Sibling tools like bus_routes or bus_stops are not 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 declare readOnlyHint=true, idempotentHint=true, etc. Description adds that it returns 'all' routes and lists specific fields, which complements 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?

Three concise sentences, each serving a purpose: action, return content, usage guidance. No fluff, front-loaded with the verb.

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

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

Given no parameters and the presence of an output schema, the description fully covers the tool's purpose and usage. No gaps.

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

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

No parameters exist, and schema description coverage is 100%. Baseline of 4 applies since description needs no additional param info.

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

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

The description clearly states it returns all WMATA bus routes with specific fields (route ID, name, line description). It also distinguishes from siblings by noting usage before fetching details or predictions.

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 context: 'Use to enumerate available routes before fetching details or predictions.' This tells the agent when to invoke it and what to do next. No when-not guidance needed due to simplicity.

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. The description adds that the tool returns stop ID, name, routes, and coordinates, which is useful but already implied by annotations.

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

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

The description is a single sentence that immediately conveys the purpose and key details. No extraneous 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 input (lat/lon, radius) and output (stop ID, name, routes, coordinates) adequately for a simple tool. An output schema exists, so full return details are not needed in the description. Minor omission: no mention of edge cases like no stops found.

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 0%, and the description only minimally explains parameters (lat, lon, radius in meters). It does not specify format constraints (e.g., decimal degrees) or limits (e.g., max radius), leaving room for ambiguity.

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 the action 'Find', the resource 'WMATA bus stops', and the key parameters (lat/lon, optional radius). It clearly distinguishes from sibling tools like bus_routes, bus_route_details, bus_incidents, and bus_predictions.

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 the tool (to find stops near a point). It does not explicitly exclude scenarios, but the context of sibling tools provides implicit differentiation.

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

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

Annotations already provide readOnly, idempotent, openWorld hints. Description adds specifics: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions.

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

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

Description is detailed but efficient, with front-loaded examples and clear structure. Every sentence adds value, though slightly lengthy.

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

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

Complete description for a comparison tool with good annotations: explains purpose, when to use, data sources, output format, and sorting. No missing context given schema covers parameters.

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

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

Schema coverage is 100%, so description adds moderate value. Provides examples of input values (tickers/CIKs for company, drug names) and reiterates 2-5 range.

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

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

Description clearly states it performs side-by-side comparison of 2-5 companies or drugs, with concrete example queries. Distinguishes from siblings (entity_profile, deep_research) by focusing on parallel comparison.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups' and provides triggering query examples. Quantifies efficiency (replaces 8-15 sequential lookups).

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 annotations already indicating readOnly, idempotent, and openWorld, the description adds substantial behavioral context: account requirements, paid tier for 'thorough', output structure (findings packet with gaps, contradictions, hops, citations), timing expectations (15-90s), semantic excerpting, and the 'never invented' guarantee. 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 long but every sentence adds value—front-loaded with the account requirement and alternative tool, then covering functionality, limitations, and output. While slightly verbose, it is well-organized and prioritized, earning a 4 for clarity despite length.

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

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

Given the tool's complexity (2 parameters, no output schema, diverse siblings), the description covers all necessary aspects: core function, decomposition mechanism, output format with evidence/citations/gaps, limitations (not for breaking news), account tiers, timing, and behavioral details like hop fields and semantic excerpting. It fully equips an agent to use and interpret results.

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

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

With 100% schema description coverage, baseline is 3. The description adds meaningful extras: that 'thorough' requires a paid plan, that 'standard' and 'thorough' return contradictions[], and that broad/multi-part questions are encouraged. These details go beyond the schema's brief descriptions, justifying a score above baseline.

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

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

The description clearly states it performs 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and explicitly distinguishes itself from siblings like ask_pipeworx (single lookup) and open-web search. The verb 'research' combined with the specific resource and contrast with alternatives gives a clear, unique purpose.

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

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

The description provides explicit when-to-use (broad/multi-part structured data questions) and when-not-to-use (breaking news, single lookups, if not signed in) guidance, naming ask_pipeworx as the alternative. It also details depth levels and second-hop iteration scenarios, enabling precise agent 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying that results are 'ready to call directly, no second schema lookup needed', which is behavioral context beyond annotations.

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

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

Description is front-loaded with purpose and usage advice, followed by examples of queries. Every sentence contributes value; slightly long but efficient given the complexity of the tool's function.

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

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

Despite lacking an output schema, the description fully explains the return format (top-N tools with names, descriptions, and full input schemas with curated examples). This is complete for a discovery tool that returns tool definitions.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds meaning by explaining that query accepts aliases (task, q, description, search) and that output includes full schemas with examples, complementing the schema.

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

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

The description uses specific verbs ('Find tools by describing the data or task') and lists many concrete domains (SEC filings, FDA drugs, etc.), clearly distinguishing this as a tool-discovery utility from sibling tools that perform specific queries or analyses.

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 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance. Does not explicitly state when not to use, but context is sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds useful behavioral context: fans out across multiple sources, soft-fails for USPTO PatentsView API sunset May 2025, and specifies that names are not supported. 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 front-loaded with trigger phrases and is dense with information. While slightly lengthy, every sentence contributes valuable guidance (e.g., output structure, soft-fail behavior, naming limitations). Could be trimmed slightly but remains efficient.

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

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

No output schema exists, but the description fully explains the return structure: cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI. Given the complexity of the tool and the context signals, the description is complete and leaves no major gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. The description extends meaning by explaining that 'type' is limited to 'company', 'value' can be ticker or zero-padded CIK, and names are not supported, adding 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 the tool produces a 'full cross-source profile of a US public company in ONE parallel call', citing specific examples ('Tell me about X', 'research Acme') and listing data sources (SEC, XBRL, USPTO, news, GLEIF). It is distinct from siblings like 'Compare Entities' or 'Validate Claim'.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and notes that names are not supported, advising to use 'resolve_entity' first. Provides clear when-to-use/when-not-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?

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds minimal context beyond 'previously stored memory'.

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

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

Two sentences, front-loaded purpose, no 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?

Covers essentials for a simple deletion tool. Could mention what happens if key doesn't exist, but usage guidelines compensate.

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

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

Schema coverage 100%, parameter description in schema is sufficient. Description does not add new semantics.

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

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

Clear verb 'Delete' and resource 'memory by key'. Distinguished from siblings 'remember' and 'recall'.

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 scenarios: stale context, task done, clear sensitive data. Suggests pairing with remember and recall.

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 (readOnlyHint, idempotentHint, etc.) already indicate safe, non-destructive behavior. The description adds value by detailing the fetch-extract-emit process and output format (single text blob for site-root/llms.txt), which enhances understanding beyond annotations.

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

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

The description is brief (3 sentences) and front-loaded with the core purpose. Every sentence adds value, and there is no unnecessary detail.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers what the tool does, its output, and use cases. It explains the return value clearly, making it complete without needing further elaboration.

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

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

Schema coverage is 100%, so the schema adequately documents both parameters (url and max_links). The description does not add significant new semantic information beyond what's in the schema, meeting the baseline of 3.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the exact actions (fetch, extract, emit) and output format. It is distinct from sibling tools like scan_competitor_ai_presence, which focus on auditing rather than generation.

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

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

Explicit use cases are provided (indexing client sites, drafting own llms.txt, auditing competitors), giving clear context. No explicit when-not or alternative tools are mentioned, but the context is sufficient to guide appropriate usage.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds value by listing return fields but doesn't introduce new behavioral context.

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

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

Two sentences, first states purpose and return fields, second gives usage guidance. Efficient and front-loaded with no wasted words.

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

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

Given the tool's simplicity (one optional param, no nested objects, no output schema), the description fully covers purpose, use cases, and return format.

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

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

Schema coverage is 100% with a good description for the 'include_inactive' parameter. The tool description doesn't add additional meaning beyond the schema.

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

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

The description clearly states 'List the caller's active subscriptions' with specific return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear 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?

Annotations provide no helpful hints (all false), so the description carries the burden. It discloses valuable behaviors: filing without an account returns a claim_token, rate-limited to 5/day, free and not counted against quota, and the team reads digests daily. 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 average but well-structured: purpose first, then use cases, exclusions, token workflow, and limits. Every sentence adds concrete operational detail; could be trimmed slightly, but the density and organization keep it focused.

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 explains what filing returns (claim_token), how to use it, rate limits, quota exemption, and precise scope boundaries. Given the tool's simplicity (4 params, one nested optional), this is fully complete for agent decision-making.

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 every parameter is already documented. The description adds workflow context for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and clarifies how type values map to the listed scenarios, which goes beyond schema but is not required for message/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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from all sibling data tools, and explicitly narrows scope to 'tools served by this Pipeworx connection,' ruling out other MCP servers.

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 triggers (bug, feature/data_gap, praise) and when-not-to-use (a different MCP server, telling the user to file it there instead). It also explains alternative workflows via claim_token retrieval, making usage conditions unambiguous.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). 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?

Two clear, well-structured sentences with bulleted use cases. Every sentence adds value. No wasted words.

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

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

No output schema, but description states returns 'top tools, top packs, and total call volume' without detailing format. Adequate for a simple trending tool with openWorldHint, but could be more explicit about return structure.

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?

Single parameter 'window' with full enum and schema coverage. Description adds meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema enum.

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

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

Description clearly states it returns top tools, top packs, and total call volume over windows. Specific verb+resource. Distinguishes from siblings like discover_tools and 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?

Lists three explicit use cases and explains window duration trade-offs. Does not explicitly exclude alternatives, but context is clear enough for an AI agent to decide.

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

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

Disclosures go well beyond annotations: semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs, >20% placeholder returns null), fill check with live CLOB depth. No contradictions with readOnlyHint/idempotentHint/destructiveHint.

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

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

Well-structured with clear sections (modes, semantic anchor, partition filter, fill check). Front-loaded with purpose. Slightly verbose but justified by tool complexity; no redundancy.

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

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

For a complex tool with 2 params and no output schema, the description covers all necessary aspects: mode selection, edge cases (similarity filter, placeholder filter), response structure, and fill check logic. Complete enough for correct invocation.

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

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

Schema coverage is 100%, yet the description adds rich context: event expects a slug or full URL, topic expects a seed question, and details how each mode processes input. This significantly enhances understanding beyond the schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific purposes. Verb+resource is precise: 'Find arbitrage opportunities on Polymarket.'

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 on when to use each mode: no args for trending scan, event for single market, topic for cross-event scan. Includes when-not instructions via fill check: 'realizable_edge_pp ≤ 0 means … do not trade it.' No ambiguity.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, so the description's additional details about edge calculation, Kelly fractions, caching, and Fed bets exclusion add substantial behavioral context. 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 well-structured with numbered segments and key terms in bold, but it is very long and dense, containing extensive details that could overwhelm some agents. It is efficient but could be more concise while retaining essential information.

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

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

Given the complexity of 9 parameters and no output schema, the description is remarkably complete. It explains response structure, edge calculation, filtering logic, caching, and diagnostics, leaving no major gaps for an AI agent to understand tool behavior.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema by explaining nuanced behaviors, such as why min_kelly does not filter partition arbs and the rationale behind default slippage. This exceeds the baseline required for fully covered schemas.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by emphasizing its discovery-oriented 'what should I bet on today' use case and detailed output structure.

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

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

The description provides clear when-to-use guidance with the phrase 'Built for "what should I bet on today"' and explains the caching behavior. It does not explicitly state when not to use this tool versus alternatives, but the context is sufficient for an AI agent to infer appropriate usage.

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

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

Annotations already declare read-only and idempotent; description adds valuable detail: data comes from daily snapshots, bounded by 60-day TTL, decay based on daily closes, not intraday, and notes that gaps mean no scan occurred. 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?

Well-structured with separate sections for response fields and limits, but somewhat verbose. Still efficient given the complexity of the telemetry data.

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?

Fully covers what the tool does, its response fields (tracked, expired, snapshot_dates), edge cases (gaps, TTL), and parameter meaning. No missing information for a tool with 2 params and no output schema.

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

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

Schema covers both parameters fully. Description adds context for days (explains default and clamp) and window (snapshot family). It also explains the response structure in detail, compensating for lack of output schema.

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

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

Description clearly states it tracks edge persistence and decay telemetry, answering a specific question about edge existence and trend. Distinguishes from sibling polymarket_edges by focusing on historical time-series rather than current snapshots.

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 context on when to use (e.g., differentiating fresh vs old wide edges) and explains limits like TTL and snapshot gaps. However, it does not explicitly contrast with siblings or specify when not to use.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral details: walks the order ladder, returns verdicts, explains basket mode risks like thin legs and forced directional risk, and warns about partial fills converting arbs to directional positions. 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?

Well-structured with clear sections (single-market, basket, warnings). Every sentence adds value, but the description is lengthy. Could be slightly more concise without losing clarity. Front-loaded with purpose.

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

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

Despite no output schema, the description thoroughly documents return fields for both modes, explains edge cases (thin legs, max_clean_notional), and covers risks. Given 4 parameters and tool complexity, it is complete for agent decision-making.

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

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

Schema coverage is 100% (baseline 3). The description adds significant meaning: explains the two modes (market vs event), default values, side auto-detection for baskets, and different interpretations of size_usd for buys vs sells and single-market vs basket. Clarifies which parameter is required depending on mode.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live order-book depth. It distinguishes single-market and basket modes, lists return fields, and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: before acting on arbitrage signals or trades above ~$500. Explains why: theoretical overround may not be capturable and partial fills cause directional risk. Lacks explicit 'when not to use', but context covers 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 set readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral context: compatibility_warning conditions, temporal_alignment, skipped_cross counters, and rarity of real spreads. 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?

Packed with info, front-loaded with purpose then modes then safety. Every sentence adds value. Could benefit from bullet formatting but remains clear and well-structured for its complexity.

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

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

Given complexity (3 params, no output schema, thorough annotations), description is remarkably complete. Explains response fields, safety warnings, edge cases. No output schema but still conveys what user receives.

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

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

Schema coverage is 100% with descriptions. Description adds meaning beyond schema: explains topic list, how explicit parameters override topic, and mode behavior. Slightly redundant with schema but adds value.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, specifies two modes (topic shortcuts and explicit tickers), and distinguishes from siblings like polymarket_arbitrage.

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

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

Provides explicit guidance on when to use (comparing spreads), when not (compatibility_warning), details two modes, and warns pre-mapped topics often return warnings. Covers when-not and 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 provide readOnly, idempotent, openWorld hints. Description adds return fields but no additional behavioral traits (e.g., rate limits, data 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?

Two sentences, front-loaded verb+resource, no redundant words. Efficient and clear.

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

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

Tool is simple with no parameters and good annotations. Description covers purpose and return fields. Could mention data freshness or confirm real-time, but adequate.

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?

No parameters exist, schema coverage 100%. Description lists return fields, adding value beyond schema. Baseline 4 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?

Clear verb 'Fetch' and resource 'current WMATA Metro rail service alerts and incidents'. Distinguishes from sibling tools like bus_incidents and other rail 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?

Description implies usage for rail incidents but does not explicitly state when to use vs alternatives (e.g., bus_incidents) or mention prerequisites.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by listing returned fields (line codes, names, station codes) without contradicting annotations.

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

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

Single sentence, no fluff, front-loaded with verb and resource. Every word is necessary and informative.

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

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

Given the tool's simplicity, the description is complete. Output schema exists to detail return values, and annotations cover behavioral traits. No gaps.

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

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

With zero parameters and 100% schema coverage, the description has no need to add parameter details. Baseline score of 4 applies.

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 'Return' and the resource 'all WMATA Metro rail lines', lists specific lines and output fields, distinguishing it from sibling tools like rail_incidents or rail_stations.

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

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

The description implies a straightforward use case but does not explicitly state when to use this tool versus alternatives like rail_stations or rail_incidents. No when-not-to-use guidance is provided.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, so the tool is safe and side-effect-free. The description adds behavioral details: the return fields (line, destination, car count, minutes until arrival) and that 'All' is a valid input. 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?

Two sentences: the first states purpose and input format; the second lists return fields. No unnecessary words. Front-loaded with the key action and resource.

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 only one parameter, an output schema (though not shown), and annotations covering safety, the description fully explains input and output behavior. It is complete for a simple data fetch 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?

With only one parameter and 0% schema coverage, the description compensates by explaining the parameter: 'comma-separated station_codes (or "All")'. This adds meaning beyond the schema's type string and aids correct invocation.

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

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

Description clearly states verb 'Fetch', resource 'real-time next-train arrival predictions', and scope 'one or more WMATA stations by comma-separated station_codes (or "All")'. It distinguishes from sibling tools like bus_predictions and rail_incidents by specifying the exact data and input format.

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 use this tool for train arrival predictions with a specific input format. It does not explicitly state when to avoid it or name alternatives, but the context of sibling tools (bus_predictions, rail_incidents) is clear enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds expected return fields but no additional behavioral context 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?

Single sentence with 18 words, front-loaded action and clear list of returns. No extraneous information.

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

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

Tool has one parameter, output schema exists, annotations cover safety. Description sufficiently explains what it does and returns. Complete for a simple lookup tool.

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

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

Schema description coverage is 0%, but description mentions station_code and that it's a WMATA code. Schema provides examples (A01, C05), partially compensating. Description could add more format guidance.

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

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

Description clearly states 'Fetch details for a specific WMATA Metro station by station_code' and lists returned fields, distinguishing it from listing tools like rail_stations.

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

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

Usage is implied via 'Fetch details for a specific station', but no explicit when-to-use or alternatives guidance compared to sibling tools like rail_stations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's mention of returning stations adds little beyond what's already known. No additional behavioral context (e.g., rate limits, pagination, or data freshness) is provided.

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

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

Two sentences, each serving a purpose: first states action and filter, second lists return fields. No redundancy, optimally front-loaded.

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

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

Given annotations and output schema (present but not shown), the description covers the main purpose and parameters. However, it lacks details about default behavior (e.g., what happens if no line_code is specified) or response format, though the output schema may address this.

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 0%, but the description compensates by clearly explaining the optional line_code parameter and what it filters. This adds meaning beyond the bare schema 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 clearly states the tool returns all WMATA Metro rail stations with optional filtering by line_code. It lists specific output fields (station code, name, line codes, lat/lng) and distinguishes it from sibling tools like rail_station_info and rail_lines.

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 mentions optional filtering by line_code, implying usage for either all stations or by line. However, it does not explicitly state when to use this tool over siblings like rail_station_info or rail_lines, nor does it provide exclusions.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping to identifier and pairing with other tools, beyond annotations.

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

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

Two sentences, front-loaded with core action, every sentence adds value. No wasted words.

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

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

For a simple tool with one optional parameter, good annotations, and clear sibling context, the description fully covers the needed information.

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

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

Schema coverage is 100% with one parameter. Description explains the listing behavior (omit key) and adds context about usage, slightly exceeding schema alone.

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

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

Clearly states the action: retrieve a saved value or list all keys. Distinguishes from siblings 'remember' and 'forget' by naming them.

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

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

Explicitly says when to use: look up previously stored context. Implies not for saving or deleting. Also mentions scoping and pairing with remember/forget.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds critical behavioral context: mark_read mutates read state (despite readOnlyHint), polling is suitable, and the feed is also accessible via a direct URL. This supplements 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 concise (4 sentences) and front-loaded with the core action. Every sentence adds essential information: what returns, what it contains, how to filter, how mark_read works, and the alternative HTTP access. 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 the return structure (source, citation_uri, raw payload), filtering, mark_read, polling, and alternative access. Given no output schema, it provides sufficient context. Minor omission: it doesn't mention pagination or limit behavior explicitly, but the schema covers limit.

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

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

Schema coverage is 100%, but the description adds meaningful value beyond the schema: it explains the purpose of each filter (type, since), the effect of mark_read on subsequent calls, and the unread_only option. It does not simply repeat schema names.

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

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

The description clearly states the tool 'pull fired events from your subscription feed' and specifies that it returns alerts with source, citation_uri, and raw payload. It distinguishes itself by explicitly mentioning filtering options and the mark_read behavior, and there are no sibling alert tools to cause confusion.

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 good usage guidance: it explains how mark_read works for polling, mentions that the same feed is available via HTTP for scripts/dashboards, and describes filtering by type and since. However, it does not explicitly compare this tool to other sibling 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 declare readOnlyHint, idempotentHint, destructiveHint. Description adds specific behavioral details: parallel call, fallback logic, soft-fail for USPTO, and return format.

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

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

The description is somewhat long but every sentence is informative. Front-loaded with purpose and usage, then details. Slightly verbose but not 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?

No output schema, but description mentions return structure (changes grouped by source, total_changes, citation URIs). Covers all key aspects for a multi-source query tool.

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

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

Schema coverage is 100%, yet description adds value: explains fans-out behavior, date format examples ('2026-04-01', '7d'), and fallback logic for the 'since' parameter.

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

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

The description clearly states the tool provides a change feed for a company across SEC, GDELT/GNews, and USPTO sources within a time window, and distinguishes it from the sibling entity_profile 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?

Explicit usage examples ('What's new with X', etc.) and guidance on when to use entity_profile instead. Also explains fallback between GDELT and GNews.

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

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

Adds behavioral context beyond annotations: key-value pair scoped by identifier, persistence differences, and pairing with recall/forget. Annotations include idempotentHint and destructiveHint, which are consistent.

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

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

Three sentences, front-loaded with purpose, then usage scenarios and technical details. No superfluous words; every sentence adds value.

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

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

Given low complexity (2 params, no output schema), description covers purpose, when-to-use, persistence behavior, and sibling tools. Complete for agent understanding.

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 already covers both parameters with clear descriptions (key with example pattern, value as any text). Description does not add new semantic details beyond schema, so baseline 3 is appropriate.

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

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

Description clearly states it saves data for later reuse across conversation/sessions, provides specific examples (ticker, address, preference), and distinguishes from siblings by mentioning recall and forget.

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

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

Explicitly states when to use (when discovering something worth carrying forward) and provides examples. Also explains persistence differences for authenticated vs anonymous users and pairs with recall/forget for retrieval/deletion.

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 readOnly/destructive annotations, the description reveals significant internal behavior: it 'cascades through several lookup endpoints internally,' degrades gracefully by still returning EDGAR identifiers if GLEIF/OpenFIGI fail, and explicitly lists unresolved identifiers under `unresolved` rather than omitting them. This adds rich behavioral context that annotations alone do not 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 long but every sentence carries essential information: examples, supported types, output specifics, fallback behavior, and efficiency claims. It is well-structured with a SUPPORTED TYPES section and front-loaded with query examples that make the tool's purpose instantly understandable.

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 shoulders the burden of explaining results. It specifies the canonical identifiers returned for companies (CIK, ticker, LEI, FIGI) and drugs (RxCUI, ingredient, brand), notes source labeling, and clarifies unresolved-identifier handling. This gives an agent sufficient context to invoke the tool and interpret responses.

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

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

Schema coverage is 100%, but the description greatly enriches the meaning of both parameters. For type=company it details the full identifier set (CIK, ticker, LEI, FIGI, ISIN handling), and for type=drug it specifies RxCUI/ingredient/brand output. It also expands the accepted input formats (ticker, CIK, ISIN, name) beyond the schema's brief examples.

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 concrete user queries ('What's the ticker for…') and defines the tool as 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes itself from siblings like entity_profile by positioning it as the first step when a name needs an ID, with an explicit 'Use FIRST' directive.

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 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use context. It also explains that it replaces 2-3 manual lookups and notes graceful degradation, but it does not explicitly name alternative tools or when-not-to-use scenarios, so it misses the top score.

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

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

The description discloses that it internally probes each entity with 'ai_visibility_check', ranks by score, and returns a list with score, confidence, and signal density. Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description adds valuable behavioral context without contradiction.

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

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

The description is four sentences, efficiently covering purpose, usage, internal mechanism, and return format without unnecessary repetition or fluff.

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

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

With no output schema, the description adequately describes the return format (ranked list with score, confidence, signal density). All 4 parameters are explained in context, use case is clear, and the tool's behavior is fully specified.

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

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

Schema coverage is 100% but the description adds meaning: it explains 'entities' array where first entry is the subject, mentions the internal call to ai_visibility_check, and clarifies the 'context' parameter for disambiguation. This enriches the parameter understanding beyond 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 'Compare AI visibility across multiple entities side-by-side', using a specific verb and resource. It distinguishes itself from sibling tool 'ai_visibility_check' (single entity) and from generic 'compare_entities' by focusing on AI visibility and ranking.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and example question. It implies when to use this tool (comparing multiple entities) but does not explicitly state when not to use it or name alternative tools for other 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds key behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeouts. 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 detailed but not overly long. Front-loaded with purpose, then specifics. Every sentence adds value, though slightly verbose. Could be trimmed slightly without losing context.

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

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

Despite no output schema, the description lists return fields explicitly (summary block with fields, per-advisory detail, links, alternative versions). Covers edge cases (partial failures, timeouts) and limitations (NPM only). Very complete for a read-only composite tool with good 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 coverage is 100% (baseline 3). The description adds context: package is 'npm package name', scoped packages accepted; version defaults to latest. Also clarifies NPM-only. Adds meaningful information beyond schema.

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

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

The description clearly states the tool's purpose as a composite check for adding an npm package, covering license, advisories, version history, and bundle size from deps.dev and bundlephobia. It distinguishes itself from sibling tools by specifying the NPM ecosystem and the specific use case ('should I add this npm package').

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: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides context on ecosystem limitations (NPM only in v1) and alternative for other ecosystems. Lacks explicit when-not usage but overall guidance is strong.

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

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

Annotations indicate idempotent, read-only, and non-destructive behavior. The description adds critical behavioral details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with 500-char overlapping windows, and caps input at 200K chars with truncation flagging.

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-front-loaded paragraph that efficiently conveys purpose, use case, benefits, pairing, and technical constraints without superfluous information.

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

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

Despite lacking an output schema, the description explains return format (passages with offsets and scores), input limits, and embedding details. It provides all necessary context for correct agent invocation.

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

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

Schema covers all parameters. Description adds meaningful examples for 'query', default and range for 'limit', and reiterates the 200K char limit for 'text', enhancing 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 performs semantic search inside a fetched record, specifying the use case when records are too large for prompts. It differentiates from siblings like ask_pipeworx_grounded by highlighting that it searches inside provided text, not external sources.

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

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

The description explicitly advises using this tool when a record is too large for the prompt and mentions pairing with ask_pipeworx_grounded for grounded reasoning. While it doesn't explicitly state when not to use it, the positive guidance is strong and provides context.

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

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

Annotations already indicate mutation and idempotency, but description adds critical details: OAuth requirement, delivery channel behavior (feed always on, email/sms optional, webhook signing, 10/day SMS cap, auto-disable after 10 failures). 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?

Well-structured with core purpose first, then types, then delivery options. Slightly verbose but every sentence adds value; could be tightened without losing information.

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

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

Given the complexity (multiple subscription types, delivery channels, and no output schema), the description is thorough: covers all parameters, constraints, and side effects (e.g., webhook secret returned once). Sufficient for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, and description enriches each parameter with concrete examples (e.g., sec_8k items, delivery validation rules, webhook secret return). Provides context beyond basic schema descriptions.

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

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

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and specifies it returns the subscription id. It lists supported types with examples, making the purpose unambiguous.

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

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

Provides explicit prerequisites (Pipeworx OAuth account, not for anonymous/BYO) and use cases for each subscription type. Does not explicitly say when not to use or compare to sibling tools, but the context from sibling names like list_subscriptions and unsubscribe implies differentiation.

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

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

Annotations already confirm read-only, open-world, idempotent, non-destructive behavior. Description adds context: returns live catalog data, no side effects. 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 dense but well-organized, starting with common query examples and then specifying details. Slightly long but every sentence earns its place. Could be slightly shorter, but still effective.

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

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

No output schema, but description thoroughly explains what is returned (category-bucketed example questions with tool+argument shapes). Covers all call patterns and parameter usage, making it complete for a discovery tool.

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

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

Schema coverage is 100%. Description adds meaning by explaining the topic parameter values (finance, pharma, etc.) and the default behavior when omitted. This goes beyond the schema's brief description.

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

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

The description clearly states it is the onboarding entry point, returning category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings like ask_pipeworx and discover_tools by specifying its role.

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 ('FIRST when you do not yet know what Pipeworx can do') and provides guidance on topic parameter ('omit for full spread' or pass specific focus). References alternatives (meta-tools) to avoid misuse.

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

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

Goes beyond annotations by explaining ownership enforcement and the soft-deactivation behavior (deactivated, not deleted), with reference to historical events via recent_alerts. No contradictions with annotations (idempotentHint=true, destructiveHint=false).

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

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

Three sentences, front-loaded with purpose, followed by critical constraints and behavior. No superfluous words; every sentence adds value.

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

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

For a simple one-parameter tool without output schema, the description covers purpose, constraint, and behavioral consequence completely, even linking to a related tool (recent_alerts). No gaps.

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

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

Input schema already describes the 'id' parameter as uuid from subscribe. Description merely restates 'by id' without adding syntax or format details. Schema coverage is 100%, 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?

Description states 'Cancel a subscription by id' with specific verb and resource. Ownership and deactivation behavior further clarify purpose, distinguishing it from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Clearly states ownership enforcement (only cancel own subscriptions) and that deactivation is soft (not deletion), implying appropriate use cases. Lacks explicit comparison to siblings but provides sufficient 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?

Goes well beyond the readOnly/idempotent annotations by explaining the decision logic for financial vs non-financial claims, enumerating the six possible verdicts, and warning that 'could_not_verify' means the check did not happen and must not be presented as evidence. This error semantics is critical behavioral disclosure not derivable from 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 efficient and every sentence adds value, but it's a single dense paragraph with no section breaks. The core purpose and usage are front-loaded, and caveats come later. Length is justified by the tool's complexity, but it is slightly verbose.

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

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

For a tool with no output schema and moderate complexity, the description fully covers routing, verdicts, error semantics, and efficiency gains. It explains what is returned (verdict + value + citation + reasoning) without needing a formal output schema. The only gap is the lack of a structured example, but overall it's 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 already describes both parameters at 100% coverage, so the description doesn't need to add parameter-level detail. It does add a hint about 'exact percent-delta math' and tolerance overriding behavior, but that's already in the schema. Baseline 3 applies.

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 natural-language trigger phrases, then states it performs 'natural-language claim verification against authoritative sources.' It clearly distinguishes this from sibling research/analysis tools by scoping it to fact-checking a user's claim and noting it replaces 4-6 sequential calls. Specific verb+resource (verify claims) makes 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?

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' — a clear trigger condition. It also differentiates two routing paths (SEC EDGAR fast path vs grounded pipeline) for financial vs non-financial claims, helping the agent decide wiring. No exclusions are stated, but the trigger is so clear that alternatives aren't needed.

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