airports

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

Annotations declare readOnly/openWorld/idempotent, and the description adds valuable behavioral context: the default free model (Workers AI Llama-3.3-70b), the cost implication of using Anthropic ('you pay Anthropic directly'), and the exact return shape (per-model {score, confidence, signals, raw_response} + combined view). 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, front-loaded with the core purpose, followed by operational specifics. Every sentence earns its place; no redundancy or filler, and the structure is easy to scan.

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

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

Despite having no output schema, the description states the return structure, default behavior, optional API key usage, and use cases. This is sufficient for an agent to decide when to invoke it, though it could hint at error scenarios or interpretation of scores.

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 each parameter already well-described (e.g., models definition includes the default and _apiKey requirement). The description repeats this information without adding new semantic value beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Probe') and resource ('one or more LLMs'), and clearly states the output ('score visibility 0-100 per model'). This distinguishes it from siblings like scan_competitor_ai_presence by focusing on general brand/topic awareness across multiple models.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly mention alternatives or when-not-to-use, but the context is clear enough for an agent to select this tool over similar ones.

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

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

Beyond the annotations, the description discloses that the tool routes questions, fills arguments, returns pipeworx:// citation URIs, and can persist context across turns. It does not discuss failure modes, rate limits, or cost, but the added behavioral context is meaningful given the read-only, idempotent annotations.

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

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

The description is front-loaded and rich, but it contains a verbatim duplicated sentence: 'But if you need to track changes over time, use recent_changes instead.' This repetition and the loose trailing sentence about news feeds make the description longer than necessary without adding proportional 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 complex routing tool with no output schema, the description explains the return value well: 'returns the structured answer with stable pipeworx:// citation URIs.' It also covers scope, examples, and a key exception. It does not specify result limits or error behavior, but the description is sufficient for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100%, and the schema already documents the question parameter and its aliases. The description adds many example questions and trigger phrases but no additional parameter-level constraints, formatting requirements, or edge-case guidance, so the baseline of 3 is appropriate.

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

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

The description clearly states that ask_pipeworx routes factual questions to a large set of verified tools and returns structured answers with citation URIs. It gives a rich domain list and concrete examples, and it differentiates itself from web search and recent_changes. However, it does not distinguish itself from similarly named siblings ask_pipeworx_beta and ask_pipeworx_grounded.

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

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

Usage guidance is explicit and strong: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions' make the intended trigger conditions clear. It also names an alternative: 'if you need to track changes over time, use recent_changes instead.'

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond those hints: the tool is experimental, routing improvements are enabled live only when a candidate is under test, and no candidate is currently active so it matches ask_pipeworx exactly. This is useful, though the phrasing 'Falls back to nothing' is slightly confusing and could have been clearer.

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

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

The description is longer than average but every sentence contributes key information: identity, current behavior, usage guidance, and reassurance that it is a fully working router. It is front-loaded with the most important facts and structured logically. Some operational detail, such as the exact retirement date, is somewhat transient but still relevant to explaining the current state.

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

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

For a tool with no output schema, the description compensates by stating that the response shape is identical to ask_pipeworx. It also clarifies the current experimental state and the absence of any active candidate, which prevents the agent from assuming different behavior. The main missing piece is a concrete description of what a response looks like, but the cross-reference to ask_pipeworx covers this adequately.

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 every parameter documented as an alias for 'question.' The description adds little parameter-level semantics beyond saying the tool accepts the same arguments as ask_pipeworx, but the schema already carries the full burden. A baseline of 3 is appropriate because the description does not need to compensate for missing parameter information.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,798 tools, arguments, and response shape. It distinguishes it from the stable router by emphasizing the experimental routing improvements and current exact-match behavior. This is a specific verb-plus-resource statement that an agent can act on and differentiate from 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?

The description explicitly tells the agent when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also implicitly names the stable alternative (ask_pipeworx) and explains that results are compared against it to decide what merges. This provides clear selection guidance without requiring the agent to infer usage from the schema alone.

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, openWorld, and non-destructive, so the bar is lower. The description adds meaningful behavior: the tool can return an explicit refusal with reasons like not_in_source, no_tool_match, tool_error, data_truncated, llm_error; it discloses costing an extra LLM call; and it states the extraction uses ONLY the tool result. That is valuable behavioral 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?

The description is dense but every sentence earns its place: behavior, return shape, refusal reasons, usage guidance, and cost tradeoff are all packed efficiently. It is front-loaded with the key differentiator (hallucination-resistant grounded answer mode). It is appropriately sized for a tool with this much decision-relevant 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?

The description explains the routing pipeline, the output contract, refusal cases, when to use it, and the cost tradeoff versus the sibling. There is no output schema, so the explicit return and refusal shape is essential and fully provided. For a complex grounded-answer tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, and the schema says the question parameter accepts several aliases. The description does not need to repeat parameter meanings; the one remaining gap is that it doesn't mention the aliases in prose, but the schema fully covers them. 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 states a specific verb+resource: it is a hallucination-resistant answer mode that routes through the same pipeline as ask_pipeworx and extracts grounded answers from tool results. It clearly distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction and refusal behavior, so an agent can tell them apart without opening schemas.

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 says when to use this tool: when an answer will be quoted, cited, or acted on and the agent must not invent facts. It also gives a when-not-to-use: prefer ask_pipeworx for casual lookups because this costs one extra LLM call. It even names the sibling alternative. This is explicit routing 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, but the description goes far beyond them. It discloses fan-out behavior, resolver contract, blocking statuses (low_confidence_match, market_closed_or_inactive), illiquid warnings, and cancellation-rule risk (refund_50_50, resolves_no_on_cancel, etc.). This is 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 well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and is front-loaded with purpose and usage. Every sentence adds operational value; there is little redundancy. Slight deduction for length, but it's appropriate for the tool's complexity.

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

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

With no output schema, the description carries full responsibility for explaining return values. It thoroughly covers result.market fields, result.analysis fields, evidence keying, resolver contract (market_match_confidence, alternatives, suggestions), parent_event extraction, news fallback fields, safety statuses, and cancellation-rule handling. This is exceptionally complete for a complex tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning to the 'market' parameter by explaining how classification drives category-specific fan-outs (e.g., BTC bet → coingecko + fred + gdelt+gnous) and by describing response shapes tied to the input. This goes beyond the schema's simple type/format description, so a 4 is warranted.

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

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

The opening line states a specific verb+resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It also gives concrete input examples (slug, URL, question text) and distinguishes itself from sibling tools by listing exact use cases like "should I bet on X." This clearly separates it from tools like polymarket_edges or polymarket_arbitrage.

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

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

The description explicitly says "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'," providing clear context for when to invoke the tool. However, it does not mention when not to use it or explicitly compare with alternatives, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint: true, openWorldHint: true, idempotentHint: true, and destructiveHint: false. The description adds useful context beyond these annotations by specifying that it returns kilometers and miles, and that it uses straight-line distance. 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 exceptionally concise, comprising two short sentences that front-load the action and resource. It includes a relevant example without any wasted words, achieving maximum information density.

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, read-only calculation tool with an output schema and comprehensive annotations, the description covers all necessary aspects: input format, operation, and output units. There are no missing requirements given the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a concrete example ('JFK' to 'LHR') and reinforces the IATA code format, but the schema already fully explains both parameters as 'IATA code of origin/destination airport'. No deeper semantics are introduced.

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

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

The description clearly states a specific verb 'Calculate' and resource 'straight-line distance between two airports', with an example that makes the purpose unambiguous. This distinguishes it from sibling tools like get_airport and search_airports, which provide different functionality.

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

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

The description implies when to use the tool (whenever straight-line distance between two airports is needed) and clarifies the input format via IATA codes. However, it does not explicitly mention alternatives or when not to use it, leaving a small gap in 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?

Goes well beyond annotations by disclosing data sources (SEC EDGAR/XBRL for companies, FAERS and FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. This is consistent with readOnlyHint, idempotentHint, and destructiveHint=false, with no contradictions.

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

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

The description is dense and front-loaded with trigger phrases and a strong preference instruction. While lengthy, each sentence contributes unique value—usage examples, data sources, sorting behavior, and efficiency benefit. Slightly overlong but appropriately structured for a complex tool.

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

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

For a tool with no output schema, the description thoroughly covers return format ('paired data + pipeworx:// citation URIs'), sorting behavior, data sources, and even handles edge cases like off-calendar fiscal years. It provides a complete picture for an AI agent to select and invoke the tool correctly.

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

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

Although schema coverage is 100%, the description adds significant meaning: it explains exactly what each type retrieves (10-K revenue, net income, cash, debt for companies; adverse-event counts, approval counts, trial counts for drugs) and clarifies value formats (tickers/CIKs vs drug names). This enriches the bare schema definitions.

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

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

The description clearly states the tool's function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It uses a specific verb ('compare') and resource ('entities'), and differentiates from sequential lookups and siblings like entity_profile by focusing on multi-entity comparison in a single call.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also lists trigger phrases ('X vs Y', 'which is bigger') and notes it replaces 8–15 lookups, effectively distinguishing from alternative approaches.

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 the tool safe (readOnly, idempotent, non-destructive), so the description adds significant beyond-annotation context: auth/paid-tier requirements, structured-source limitation, decomposition and parallel routing behavior, return packet contents (evidence, confidence, citation_uri, hop), explicit gaps[] rather than invented answers, contradictions[] for standard/thorough, semantic excerpting, and latency. No contradiction with annotations exists.

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

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

The description is long but dense and front-loaded with the most decision-critical facts (account requirement, alternative, core purpose). There is some redundancy with the schema's depth enum text and a few run-on parentheticals, but every sentence carries actionable information for an agent.

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

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

With no output schema, the description fully explains the return structure: findings packet with verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, explicit gaps[], contradictions[], and hop field. It also covers error behavior (never invents answers) and performance expectations (15-90s). An agent has everything needed to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining what depth values concretely do (single hop, gap-recovery hop, iterative chase for thorough) and confirms the question parameter is intended for broad/multi-part natural language. This is a meaningful semantic upgrade over the schema alone.

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

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

The description states a specific resource and action: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in a single call, with an explicit negative scope ('this is NOT open-web search'). It also distinguishes itself from ask_pipeworx ('For a single lookup use ask_pipeworx'), so the agent can tell the tools apart at a glance.

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 when-to-use guidance is present: 'Best for broad/multi-part questions over structured data', plus clear alternatives with conditions: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx'. This gives both positive and negative selection criteria.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the bar is lower. The description adds valuable behavior: returns top-N tools with names, descriptions, and full input schemas with curated examples, and guarantees 'no second schema lookup needed.' 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, front-loading the core purpose and then efficiently covering usage, return value, and strategic advice. Every sentence adds value without redundancy.

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

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

Given no output schema, the description adequately explains the return format (names, descriptions, full schemas, examples). It covers purpose, usage, and output, but doesn't address edge cases like empty results or relevance ranking, leaving a minor gap.

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

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

Schema coverage is 100% with detailed descriptions for all six parameters, including aliases and limits. The description adds little beyond the schema, simply mentioning 'top-N' without specifying default/max, which the schema already covers. 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 opens with 'Find tools by describing the data or task,' providing a specific verb and resource. It further distinguishes this tool from siblings by listing the broad domains it covers and emphasizing its meta-discovery role ('Call this FIRST...').

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and advises calling it first when many tools are available. However, it doesn't name alternative tools or explicitly state when not to use it, so it lacks complete 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?

Beyond readOnly/idempotent annotations, it discloses fan-out behavior, a 10-K sorting detail, patents API sunset with soft-fail, FDA empty-as-expected semantics, GDELT→GNews fallback, and sources_used/sources_failed reporting. This is deep behavioral transparency.

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

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

The description is dense but every segment earns its place: usage examples, preference rule, outputs, edge cases, input formats. Key guidance is front-loaded before implementation details.

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

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

With no output schema present, the description must carry the full return contract, and it does: field-by-field results, caps, URIs, source-specific failure modes, and expected-empty sections. An agent has enough to invoke and interpret the tool correctly.

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

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

Although schema coverage is 100%, the description materially extends the schema by explaining that type is interchangeable, value can be ticker/CIK/name, name resolution happens via SEC EDGAR, and private companies yield resolved:false with a notes line rather than a failure.

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 opens with concrete query patterns and states the tool produces a full cross-source profile of a US public company in one parallel call. It names the resource (company profile) and the scope, distinguishing it from single-pack SEC/XBRL/news lookups even without naming siblings.

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

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

The description explicitly says ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also specifies accepted input formats and what happens for private companies, giving clear boundary conditions.

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

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

Annotations already declare destructiveHint and idempotentHint, and the description is consistent. It adds context about the nature of the data ('sensitive data') and when deletion is appropriate, going beyond the bare annotation.

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 focused sentences: the first states the action, the second provides usage scenarios and sibling pairing. No unnecessary 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 single-parameter delete tool with annotations covering destructive/idempotent behavior, the description covers purpose, usage, and pairing. It doesn't explain error handling for missing keys, but the idempotent annotation mitigates that.

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

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

The schema already provides 100% coverage for the single 'key' parameter with a description. The tool description mentions 'by key' but doesn't add meaningful semantics beyond the schema, so 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 uses a specific verb 'Delete' and a clear resource 'previously stored memory by key,' making the tool's function obvious. It also distinguishes from sibling tools by referencing pairing with remember and recall, indicating this is the deletion counterpart.

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

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

It explicitly states when to use the tool: when context is stale, task is done, or clearing sensitive data. This gives clear context, though it lacks an explicit 'when not to use' statement, so it's not a perfect 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds value by explaining the behavior of fetching the page, extracting content, and emitting a markdown text blob, which goes beyond the annotation hints. 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 two sentences plus a concise bullet-like list of use cases. It front-loads the core purpose and process, with every sentence contributing meaningful information and no redundancy or fluff.

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

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

For a tool with only 2 parameters, full schema coverage, and supportive annotations, the description thoroughly covers purpose, process, output format, and use cases. It does not delve into error handling or edge cases, but those are not essential for a clearly-scoped read-only tool, so 4 is appropriate.

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

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

Schema description coverage is 100% and both parameters (url and max_links) have clear descriptions in the schema. The tool description does not add parameter-specific details beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb 'Generate' and identifies the resource 'llms.txt file for any URL'. It details the process (fetches page, extracts title/description/key links, emits markdown) and includes use cases that distinguish it from sibling tools like scan_competitor_ai_presence, making the tool's purpose unambiguous.

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

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

The description explicitly lists three use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), providing clear context for when to use the tool. It does not explicitly name alternatives or state when not to use it, hence 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety and side-effect profile. The description adds the return fields but does not disclose any additional behavioral traits such as potential errors, caching, or data freshness. Given the strong annotation coverage, the description provides modest extra context.

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

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

The description is two concise sentences, front-loaded with the action and scope, then a clear list of return fields. Every word earns its place, and there is no redundancy or filler.

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

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

For a simple lookup tool with one parameter, a rich output schema (implied by 'has output schema: true'), and strong annotations, the description is largely complete. It covers the purpose, parameter, and return values. It does not mention error handling or invalid code behavior, but given the tool's simplicity and existing schema, this is a minor gap that does not undermine usability.

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

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

Schema description coverage is 100% for the single parameter (iata_code) with a clear description. The tool description repeats the code examples ('JFK', 'LHR') already present in the schema, adding no new semantics. Since the schema already fully documents the parameter, the description does not significantly enhance parameter 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 uses a specific verb ('Get') and clearly identifies the resource ('airport details by IATA code'). It also lists the specific details returned (name, city, country, coordinates, altitude, timezone). While it does not explicitly differentiate from sibling tools like search_airports, the 'by IATA code' scope implies a distinct lookup mechanism, making the purpose clear.

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

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

The description implies usage context: when you have an IATA code, you can retrieve airport details. However, it does not explicitly state when to use this tool vs. the sibling search_airports, nor does it provide any exclusions or alternatives. The guidance is thus inferred rather than stated.

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 false, so safety is covered. The description adds valuable context about the caller-specific scope ('the caller's') and the return payload (fields listed), which goes beyond the annotations. No contradictions or surprising behaviors are hidden.

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 short, information-dense sentences. The first states the action, the second lists return fields, and the third gives usage context. No filler words or redundant information. Front-loaded with the essential 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?

For a simple read-only list tool with one optional parameter and no output schema, the description covers all essential aspects: what it does, what it returns, when to use it, and implicit scoping. The annotations cover safety, and the schema covers parameters, so the description rounds out the picture nicely.

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

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

The schema provides 100% coverage for the single parameter include_inactive, including a description. The tool description does not add any additional meaning to the parameter, so the schema carries the burden. 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 verb 'List' and the resource 'the caller's active subscriptions', immediately distinguishing it from sibling tools like subscribe/unsubscribe. It also enumerates the exact returned fields (id, type, params, etc.), leaving no ambiguity about the tool's function.

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

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

The description explicitly provides usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool, though it doesn't explicitly mention when not to use it or alternatives. Still, the guidance is clear and practical.

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 are minimal (all hints false), so the description carries the full burden. It discloses key behavioral details: claim_token mechanics for follow-up without an account, rate limit of 5 per identifier per day, daily digest consumption, roadmap impact, and that it's free and doesn't count against tool-call quota. These details go beyond what annotations or schema provide, offering rich contextual transparency.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose before diving into use cases, exclusions, and operational details. Every sentence earns its place: usage criteria, MCP boundary, token mechanism, rate limit, and roadmap impact. No filler or redundancy.

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

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

Given the tool's moderate complexity (nested context object, 4 params, no output schema), the description is highly complete. It explains the return value mechanism (claim_token) and how to read status later. Minor gaps exist, such as not explicitly describing the response format for the initial filing beyond the claim_token, but the core usage is fully covered.

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

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

Schema coverage is 100% and the schema descriptions are already detailed (e.g., enums, context fields). The description adds extra semantic value by advising users to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts, which clarifies message content. It also explains the claim_token parameter's dual use (follow-up vs. original filing). This slightly exceeds the baseline for full schema coverage.

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

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

The description 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 sibling tools (e.g., ask_pipeworx, discover_tools) by focusing on feedback about Pipeworx tools themselves. The purpose is unambiguous and action-oriented.

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 conditions: bug, feature/data_gap, or praise. It also gives a strong exclusion criterion: do not use for tools from other MCP servers, and provides a fallback method ('file it with that server instead'). The 'Not sure?' clarification further guides the user. This is exemplary usage 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 declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond these: it reveals the data source ('derived from CF analytics-engine'), privacy handling ('no PII'), the exact output granularity ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This fully discloses the tool's internal behavior and data provenance, exceeding the annotation baseline.

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

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

The description is well-structured and front-loaded: the first sentence immediately states what the tool returns, followed by a numbered list of use cases, and ends with technical notes on data source and caching. Every sentence contributes unique value with no filler. It is appropriately sized for a tool with this level of nuance.

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

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

The tool is simple (one optional parameter, no output schema) and the description covers all essential aspects: return value (top tools, top packs, total call volume), data source, privacy, caching, and usage context. Since there is no output schema, the description reasonably conveys the output structure by mentioning '(pack, tool, count)'. The combination of annotations and description provides complete context for an agent to select and invoke this tool.

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

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

The only parameter 'window' has 100% schema description coverage: the schema already explains the enum values and their semantics ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.'). The main description mentions the windows but adds no additional meaning beyond the schema. With high schema coverage, the baseline is 3.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' This is a specific verb ('Returns'), resource ('Pipeworx trending data'), and scope ('over a recent window'), and it distinguishes itself from siblings like discover_tools by focusing on current aggregated agent usage rather than general tool discovery. The 'Self-aggregating signal' phrase further differentiates it.

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

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

The description provides three explicit use cases: 'discovering what data sources are hot for current events,' 'confirming a popular tool is the canonical choice before asking your own question,' and 'seeing whether your use case aligns with what most agents need.' These give clear context for when to use the tool. However, it does not name alternative tools or explicitly state when NOT to use it, so it falls short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses material behavior: the 0.30 Jaccard semantic anchor, the placeholder-filter threshold (>20% returns null), and the fill-check against live CLOB depth with a clear 'do not trade it' warning when realizable_edge_pp ≤ 0. This is rich behavioral context with no contradiction to annotations.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core call pattern. It earns its length by packing essential thresholds, examples, and response details without redundancy, fitting the tool's complexity.

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

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

With no output schema, the description compensates by specifying the response shape (opportunities[] with gap_pp, suggested_trade, reasoning, and partition_check fields). It also covers edge cases, mode selection, and references polymarket_fill_risk, making it fully self-sufficient for an agent to invoke correctly.

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

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

Although the schema already covers both parameters with 100% coverage, the description goes substantially further by providing concrete slug/topic examples, explaining how each mode changes the scan (event walks child markets; topic flattens related events), and clarifying the semantics of the Jaccard filter. It adds meaning beyond the schema's property descriptions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the three call modes (trending_scan, event, topic) and even names polymarket_fill_risk as the sizing alternative, so it stands apart from sibling tools.

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

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

Explicit when-to-use guidance is provided for each parameter combination: call with no args for trending_scan, pass event for a specific market, or pass topic for cross-event scanning. It also recommends event for specific markets and points to polymarket_fill_risk for custom sizing, fully covering 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?

Beyond the read-only/idempotent annotations, the description discloses significant behavioral traits: caching at the KV level for 1 hour, internal threshold changes (Run 8 relaxed gates), why fed_candidates are excluded, the 24h-move warning, and detailed filter logic. This gives the agent a rich understanding of runtime behavior.

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

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

The description is extremely long and dense, covering many edge cases and internals. While it is structured with clear sections and no filler, its length may reduce skimmability. It is more than necessary for basic usage, but each sentence does add some value.

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

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

With no output schema, the description fully documents the response structure, including by_segment, fed_candidates, and _diagnostics. It also explains why segments may be empty and what each field represents, ensuring the agent knows exactly what to expect from the tool.

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

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

The input schema already has 100% documentation coverage, but the description adds context beyond the schema. It explains the 'TRADEABLE-EDGE KNOBS' and clarifies subtle interactions like min_partition_leg_kelly applying to per-leg Kelly rather than parent-level, which is not obvious from the schema alone.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and differentiates it from siblings by emphasizing Pipeworx data and the 'what should I bet on today' use case.

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

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

The description provides clear usage context with 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' However, it does not explicitly mention when not to use this tool or name alternative sibling tools, so it lacks explicit 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description extensively discloses response structure, semantics of trend and decay_pp_per_day, the meaning of snapshot gaps, and limits like TTL and daily closes. This goes far beyond what annotations provide, making the tool's behavior highly predictable.

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?

Although long, the description is exceptionally well-structured and dense with information. It opens with the core purpose, then organizes args, response format, and limits in clearly labeled sections. Every sentence earns its place, with 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?

The description compensates for the lack of an output schema by fully specifying the response object (tracked, expired, snapshot_dates) and their semantics. It also covers historical limitations (TTL, snapshot gaps) and data nuances (net slippage), making the tool fully understandable without external context.

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

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

The schema covers both parameters (days, window) with descriptions, so baseline is 3. The description adds meaningful context: days is a lookback with default 14 and max 30, and window refers to a snapshot family, tying parameters to the snapshot architecture. This enhances understanding 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 clearly states a specific purpose: tracking edge persistence and decay from daily snapshots. The verb 'tracker' plus the phrase 'Answers "how long has this edge existed and is it shrinking?"' makes the function unambiguous, and the contrast with fresh vs. old edges distinguishes it from sibling tools like polymarket_edges.

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

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

The description provides clear context for when the tool is relevant: when assessing whether an edge is still worth taking based on its age and decay. It does not explicitly name alternative tools or provide when-not-to-use guidance, but the context strongly implies this is for historical persistence analysis rather than current edge discovery.

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

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

The description discloses several behavioral traits not captured in annotations: it 'walks the ladder,' requires one of market or event, returns a verdict, and warns about partial fills creating 'unhedged directional position.' It also adds safety context (forced_directional_risk, thin_legs) and explains the consequences of misuse, which 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 appropriately so for a dual-mode tool with complex return fields. It is front-loaded with the core purpose, then logically broke into SINGLE-MARKET, BASKET, and usage guidance; no sentence is filler. Could be slightly tightened but structure earns high marks.

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

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

Even without an output schema, the description enumerates every important return field for both modes (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, profit_usd, thin_legs, etc.), mentions edge cases (partial fills, thin books, forced directional risk), and clarifies defaults and clamps. It is fully self-contained for an agent to know what to expect and when to use it.

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

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

Schema coverage is 100% (baseline 3), but the description adds meaningful semantics beyond raw schema: size_usd is 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional' for basket; side has explicit default behavior per mode. It also clarifies the mutually exclusive requirement of market vs event, which the schema only implies.

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

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

The description opens with a specific verb-resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes three modes (single-market, basket, and auto), and the unique value proposition is evident from the start, establishing it as distinct 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?

Usage guidance is explicit and actionable: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk rationale (thin books, unhedged directional positions), giving agents clear criteria for when this tool is required versus optional.

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

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

The description goes far beyond the readOnly/idempotent annotations by disclosing how matching works (keyword and word overlap, not a shared resolution source), the gross-vs-net fee caveat, the meaning of compatibility_codes, the fact that unclassified legs are never paired, and that temporal_alignment null means 'could not compute,' not 'aligned.' This is exceptional behavioral disclosure.

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

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

The description is long, but dense with safety-critical details that are hard to convey in fewer words. It is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and front-loads the core concept. A few redundancies exist, such as restating temporal alignment caveats in multiple places, but overall the length is justified by the tool's complexity.

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

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

With no output schema, the description must carry the burden of explaining the return shape, and it does. It covers leg-by-leg prices, top_spreads_pp, compatibility_warning and codes, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters. For a tool this intricate, the description is remarkably 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 documents all three parameters with descriptions and examples, giving 100% coverage. The description adds value by explaining that the explicit ticker and slug override the topic-mapped side, and that both modes run the identical matcher. This clarifies parameter interaction beyond the schema, though it does not transform understanding of any single parameter.

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

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

The description opens with a precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the two venues, the object being compared (the same outcome), and the tool's role in computing the price delta. This strongly differentiates it from Polymarket-only siblings like polymarket_edges and polymarket_arbitrage.

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

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

The description explicitly explains the two invocation modes—pre-mapped topic shortcuts versus explicit ticker/slug pairings—and when each is appropriate. It also warns that pre-mapped topics often do not yield tradeable spreads. However, it does not explicitly name an alternative sibling tool for cases where the user should not use this tool, so it stops just short of full alternative routing.

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 behavior, lowering the burden on the description. The description adds valuable context by explaining scoping (anonymous IP, BYO key hash, account ID) and the special behavior of omitting the key argument to list all keys, which goes beyond what annotations 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 concise (three sentences) and front-loads the primary action. Each sentence provides distinct, necessary information: the operation, use case, and scoping/companion tools, with no redundant wording.

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 and no output schema, the description is comprehensive. It covers the operation, usage scenario, scoping, and relationships with sibling tools, so the agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100% with the key parameter described as 'Memory key to retrieve (omit to list all keys)', matching the description closely. The description adds contextual value by connecting the key to values 'previously saved via remember', reinforcing the parameter's role in the memory workflow.

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 ('Retrieve', 'list') and clearly states the resource (values saved via remember), making the tool's function unambiguous. It also distinguishes itself from siblings by explicitly naming remember and forget as companion operations, which clarifies its unique role in the memory lifecycle.

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

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

The description provides clear context for when to use the tool ('look up context the agent stored earlier'), and explicitly pairs it with remember and forget. However, it does not explicitly exclude alternative tools or list when-not-to-use scenarios, though the internal memory use case is well implied.

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. The description adds valuable behavioral detail: each event carries source, citation_uri, and raw payload; mark_read flags events; feed is persisted; and the same feed is available via HTTP. 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?

Four sentences, front-loaded with the core purpose, and each sentence delivers unique, non-redundant information. No filler or wasted words.

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

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

With no output schema, the description adequately covers return payload details, filtering options, mark_read semantics, and the alternative HTTP access point. It is complete for a read-only tool with well-documented parameters and annotations.

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

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

Schema coverage is 100% and each parameter is described. The description supplements with a concrete filter example ('sec_8k'), clarifies mark_read side effects, and explains the returned event structure, 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 function: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts the evaluator has written to your persisted feed'. This specific verb+resource distinguishes it from sibling tools like list_subscriptions and recent_changes.

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

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

The description provides clear usage context: filtering by type and since, polling behavior, and the alternative HTTP endpoint for scripts. It does not explicitly name sibling alternatives or exclusions, but the practical guidance is sufficient.

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

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

Beyond the readOnly/idempotent hints, the description discloses the exact data sources, fallback behavior, soft-fail condition for USPTO, rate-limit handling, and return shape (changes[] grouped by source). 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?

Though long, the description is front-loaded with use cases and every sentence carries critical operational detail (sources, fallback, parameter formats, output summary). No fluff; the density is justified by tool complexity.

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

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

With no output schema, the description compensates by outlining the response structure (changes[], total_changes, citation URIs). It also covers data source fallback and limitations, making it complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds significant value by explaining `since` formats (ISO and relative shorthand), typical usage ('30d' or '1m'), and giving concrete examples for `value` (ticker or CIK). This exceeds baseline interpretation.

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 change feed for a company over a time window, covering SEC, news, and patents. It uses specific verbs like 'change feed' and explicitly distinguishes from sibling tool entity_profile, telling the agent when to use which.

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 query examples ('What's new with X'), explains the fallback logic (GDELT to GNews), and names the alternative tool entity_profile for static profiles. This is direct when-to-use guidance with 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?

Beyond annotations, the description discloses persistence and scoping behaviors: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours' and 'scoped by your identifier'. This adds meaningful context consistent with the idempotentHint annotation.

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?

Four focused sentences, front-loaded with the core action. Each sentence adds value: purpose, when-to-use, storage format, and persistence/companion tools. No redundant information.

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

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

For a simple two-parameter tool with no output schema, the description is fully complete. It covers purpose, usage, scope, persistence, and related tools, making it easy for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with detailed key/value descriptions, so the baseline is 3. The description adds purpose and scope context but does not introduce new parameter-specific semantics beyond what the schema already provides.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Save data the agent will need to reuse later'. It distinguishes itself from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete'.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. It names alternatives (recall, forget) but does not explicitly state when not to use the tool, so a near-perfect score is warranted.

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 readOnly, openWorld, idempotent, and non-destructive behavior, and the description adds substantial behavioral detail beyond that. It discloses graceful degradation when GLEIF/OpenFIGI are unavailable, explicitly states that unresolved identifiers are reported under `unresolved` rather than omitted, and explains how ambiguous FIGI matches are handled via `figi_candidates`. It also documents that each call cascades through multiple lookup endpoints, replacing manual lookups.

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

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

The description is long and dense, but almost every sentence adds needed information for a tool that spans two entity types and multiple identifier sources. It is front-loaded with the core purpose and usage rule, then organized into SUPPORTED TYPES with sub-details. Only mild trimming would be possible without losing essential edge-case guidance.

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

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

Even without an output schema, the description covers what the tool returns, how identifiers are labeled, what happens when resolution fails or is ambiguous, and how the tool behaves under partial upstream outages. It also explains the identity-source rationale for company, drug, and non-US issuer coverage. For a tool with this much behavior, the description is remarkably complete.

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

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

Schema coverage is 100%, but the description adds meaningful guidance well beyond the schema. It gives concrete examples for both type and value, explains what kinds of inputs are accepted (ticker, CIK, ISIN, name), and includes a critical usage warning about passing the issuer name exactly rather than the full question phrase. The bond example is especially valuable because it prevents a realistic failure 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 names a specific verb and resource: resolving a user-spoken name to canonical official identifiers other tools consume. It enumerates concrete query phrasings, supported entity types, and the identifier sets produced, making it easy to distinguish from siblings like entity_profile or validate_claim. It also clarifies that it is the correct first stop when a name needs to become an ID.

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

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

The description explicitly says "Use FIRST whenever you have a name but need an ID," which gives an affirmative trigger for invocation. It also warns that non-equity instruments resolve here and that multi-match instrument names return candidates rather than asserting a single answer. It does not name specific alternative tools to use when the goal is not name-to-ID resolution, so it falls short of the full when-not guideline.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also discloses return fields (score, confidence, signal density), which is useful 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 three succinct sentences, front-loaded with the primary action. Every sentence earns its place: purpose, operation, use case, and output. There is no fluff or repetition.

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

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

For a tool with 4 parameters, no output schema, and moderate complexity, the description covers the core aspects: what it does, how it works (probe, rank, surface), when to use it, and what it returns. The lack of an output schema is compensated by explicitly listing returned fields (score, confidence, signal density).

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema—it references 'your brand + N competitors' but the schema already explains first entry as subject. No additional parameter semantics are provided.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from sibling ai_visibility_check by focusing on multi-entity comparison and ranking, and from compare_entities by mentioning AI visibility scoring.

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

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

The description provides clear context for when to use the tool, explicitly stating it is 'Useful for competitive AI-marketing audits' and giving an example query. However, it does not explicitly mention when not to use it or provide alternatives, though it implicitly contrasts with ai_visibility_check by describing probing behavior.

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?

Even though annotations already declare readOnlyHint and idempotentHint, the description adds valuable behavioral detail: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and the sources_failed field will list timeout issues while the rest still returns. This goes 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?

The description is information-dense but every sentence earns its place: main purpose, fan-out targets, exact use cases, ecosystem limitation, partial failure behavior, latency, and return fields. It is front-loaded with the core purpose and contains no fluff.

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

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

Given there is no output schema, the description thoroughly lists the full return structure (summary block fields, per-advisory detail, links, alternative versions) and covers partial failure behavior, latency, and ecosystem constraints. This makes it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% for both parameters, and the schema already explains package name (including scoped packages) and version defaulting. The description does not add parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ("check") and resource (npm package), and distinguishes it from siblings by describing the composite fan-out across deps.dev and bundlephobia. It answers the exact question "should I add this npm package to my project".

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 when-to-use guidance is given: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'". It also excludes non-NPM ecosystems and directs the user to deps.dev:version directly for PyPI/Maven/Cargo/Go, providing clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations: the bundled map of 150 hubs, the behavior of returning all primary airports for multi-airport cities, and the limitation that city lookup only works for bundled airports.

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

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

The description is two sentences, with the first stating input types and the second explaining scope and limitation. All sentences earn their place, with no fluff or redundancy, and the key information is front-loaded.

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

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

Given the output schema exists and annotations cover safety, the description is complete: it explains input types, behavior, scope, limitations, and an alternative for non-bundled airports. The tool is simple (1 param) and the description fully covers usage context.

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

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

Schema coverage is 100% (query described as city or IATA code with examples), so baseline is 3. The description adds meaning by explaining that city lookup relies on a bundled map of 150 top hubs and that multi-airport cities return all primary ones, which is not in the schema.

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

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

The description uses a specific verb ('look up') and resource ('airport'), and clearly distinguishes the tool's scope by specifying input modes (city name or IATA code) and the bundled map limitation. This separates it from sibling tools like get_airport or more comprehensive search alternatives by explicitly noting the top-150-hub limitation.

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

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

It explicitly states when to use the tool: for city name or IATA code lookups within the bundled map of 150 hubs. It also provides when-not guidance: for airports not in the bundle, pass an IATA code or use the aviationstack pack for full-text name/country search, naming an alternative.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description reveals significant behavioral details: the embedding model (BGE-base-en), windowing strategy (500-char overlapping windows), length cap (200K chars), truncation flagging, and the presence of offsets for verification. This adds substantial context beyond what annotations provide and contradicts nothing.

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 two sentences but remains focused and front-loaded with the core purpose. Every sentence adds value, from the use case to the technical details. The degree of implementation detail is slightly more than necessary, but it is efficiently packed and logically ordered.

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 sufficiently explains return values (passages with character offsets and similarity scores). It covers the input requirement (text and query), the use case context, the pairing with sibling tools, and edge behavior (truncation). This makes the tool's behavior fully transparent for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some context (e.g., text examples like SEC 10-K body, query examples), but these largely mirror the schema descriptions. The description does not introduce new parameter-level details beyond the schema, so a 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 a specific verb+resource: "Semantic search INSIDE a fetched record." It includes concrete outputs (top-N passages with character offsets and similarity scores) and distinguishes from siblings like ask_pipeworx_grounded by explaining its role in a workflow (fetch first, then search inside).

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

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

The description explicitly says when to use this tool: "Use when the record is too big to cram into the prompt." It also names an alternative and pairing: "Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document." This provides both when and alternative guidance.

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

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

Given the annotations already declare readOnlyHint=false, openWorldHint=true, etc., the description adds valuable behavior context: the OAuth account requirement, phone verification for SMS, and a 10/day cap. It also discloses the return value (subscription id). These details go beyond what the annotations provide, though they do not cover every edge case (e.g., webhook auto-disabling, which is in the schema).

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

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

The description is dense but every sentence serves a purpose: purpose, return value, prerequisite, supported types with examples, and delivery channels. It is front-loaded with the main action and structured logically, with no filler or redundant content.

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

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

Despite having no output schema, the description states the return value (subscription id) and comprehensively covers the main behavior: types, parameters, delivery options, and constraints. The webhook details are left to the schema, which is acceptable given the schema's richness. The tool's complexity is well addressed.

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

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

The schema already provides 100% parameter coverage with detailed type-specific examples. The description adds interpretive meaning beyond the schema, such as explaining that items:["5.02"] means an officer change in an 8-K filing, and clarifying the semantics of the delivery feedback fee. This enriches the raw schema, but the schema itself is already strong, so the added value is moderate.

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

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

The description starts with a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It lists supported subscription types and distinguishes this tool from siblings like list_subscriptions and unsubscribe by focusing on creation and returning a new subscription id.

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

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

It provides clear context for use (proactive monitoring), explicitly states a prerequisite ('Requires a Pipeworx OAuth account') and a limitation ('anonymous + BYO cannot persist subscriptions'), and mentions an alternative for consuming the feed via recent_alerts or a GET endpoint. However, it does not explicitly name alternative tools for managing subscriptions (e.g., list_subscriptions), so it falls slightly short of full explicit when-not/alternatives guidance.

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

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

The annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context beyond these: it explains that it draws from a live catalog, returns a specific output structure (category-bucketed questions with tool/argument shapes), and that passing no arguments gives the full spread while passing a topic focuses results. This goes beyond what the annotations provide, though it doesn't go into exhaustive detail about response formatting.

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

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

The description is a single dense paragraph but every sentence contributes useful information: purpose, usage context, parameter behavior, and return value. It's somewhat long, but not wasteful. The structure could be improved with bullets, but the current format is still scannable and information-rich.

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 (0 required parameters, 1 optional) and the absence of an output schema, the description fully covers what it does, when to use it, how to call it, and what to expect in return. It explains the categories, the optional `topic` parameter, and the fact that it draws from a live catalog. 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 schema already provides 100% coverage for the single parameter `topic`, listing the exact valid values and explaining that omitting it yields a cross-category spread. The description adds only a brief example ('e.g. "finance", "pharma", "betting"'), which doesn't significantly enhance the schema's meaning. Thus, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: it returns category-bucketed example questions with the exact tool and argument shape to answer them. It explicitly identifies itself as the onboarding entry point ('What can I ask Pipeworx?') and distinguishes it from siblings by saying 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also mentions alternatives by naming the meta-tools (ask_pipeworx, entity_profile, compare_entities) as things you'll learn to call. However, it doesn't explicitly state when not to use this tool, so it stops short of a 5.

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

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

The description discloses that the row is deactivated rather than deleted, which adds meaning beyond destructiveHint=false in annotations. It also clarifies ownership enforcement. This goes beyond the minimal annotation context, though it doesn't cover idempotency or error behavior.

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

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

Two sentences with no redundancy. The first sentence states the action, the second provides crucial behavioral details. Every word 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 single-parameter tool with available annotations, the description covers the core behavior, ownership rules, and post-cancel state. It doesn't mention return values or error cases, but these are less critical for a simple cancel operation.

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

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

The schema already fully describes the id parameter (100% coverage), including its source from subscribe. The description simply says 'by id' without adding new syntax or format details, so it meets the baseline for high schema coverage.

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

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

The description begins with 'Cancel a subscription by id,' which clearly identifies the action and target. It distinguishes from siblings like subscribe and list_subscriptions by describing the cancellation semantics and ownership constraint.

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

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

The description provides clear context on when to use the tool (to cancel a subscription) and includes important constraints (ownership enforcement, soft-delete effect). However, it doesn't explicitly mention alternatives or when not to use it, which would push it to a 5.

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

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

Annotations already declare read-only, idempotent, and open-world behavior; the description adds substantial context beyond these: the two pipeline paths (SEC EDGAR/XBRL for financial vs grounded pipeline for others), the full verdict taxonomy, and the crucial warning that could_not_verify is a failed-check signal, not evidence for/against the claim, while unsupported means no source coverage. This prevents serious misinterpretation of results.

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

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

The description is information-dense yet well-organized: trigger phrases, core purpose, usage condition, pipeline behavior, return values, and a critical caller caveat. Every sentence earns its place, and the structure front-loads the most important operational detail early for agent guidance.

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

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

With no output schema, the description fully covers the return contract: verdict values, grounded/structured actual value with pipeworx:// citation, and reasoning. It also explains the two routing paths and failure semantics, making the tool self-contained for an agent to invoke and interpret results correctly. No important gap remains.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds value by explaining that tolerance_pct overrides the claim-wording default, is capped at 5, and should be set to 1–2 for hallucination detection. It also provides claim examples that illustrate what natural-language claims look like, aiding parameter selection.

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

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

The description explicitly states the tool's function: natural-language claim verification against authoritative sources, with concrete trigger phrases like "fact check" and "verify the claim that…". It clearly distinguishes itself from sibling research/search tools by focusing on verdict generation for factual claims, not open-ended research.

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

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

The description gives clear usage context: "Use whenever the agent needs to check whether something a user said is factually correct." It also explains the routing between financial and non-financial claims and notes it replaces multi-step manual verification. However, it lacks explicit external alternatives or when-not-to-use conditions, so it stops short of full exclusion guidance.

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