Bnr Ro

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

Annotations already indicate safe read-only operation. Description adds value by explaining default model, optional Anthropic key, and per-model response structure including score, confidence, signals, raw_response. No contradiction with annotations.

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

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

Description is well-structured: purpose first, then default behavior, optional param, output shape, use cases. Slightly verbose but every sentence adds value. Could tighten slightly, but effective.

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

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

Despite no output schema, description fully covers return values (per-model object with score, confidence, signals, raw_response plus combined view). Explains all parameters and optional API key. Complete for a moderate-complexity tool.

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

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

Schema coverage is 100%, but description adds practical context: default model is Workers AI Llama-3.3-70b (free), _apiKey for Anthropic is passed straight through, and context helps disambiguate. These details clarify parameter usage beyond schema descriptions.

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

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

Description clearly states the tool probes LLMs for brand/business visibility and returns a score. Uses specific verbs (probe, score) and resource (LLMs). Distinguishes from siblings like ask_pipeworx by explicitly mentioning AI-marketing audits and competitive monitoring.

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 mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Does not state when not to use or name alternatives, but context is clear enough.

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

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

Annotations already indicate read-only (readOnlyHint=true), open-world, and idempotent. The description adds meaningful context: routes the question to the right tool, fills arguments, returns structured answer with stable pipeworx:// citation URIs, and works on every tier with one fast call. No contradiction with annotations.

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

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

The description is longer than average, but every sentence delivers value: purpose, examples, alternative references, and usage context. It is front-loaded with 'PREFER OVER WEB SEARCH' and structured logically, which justifies its length without being wasteful.

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

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

No output schema exists, so the description compensates by specifying the return format: 'structured answer with stable pipeworx:// citation URIs'. It covers when to use, what data domains are covered, and how it relates to sibling tools, making it fully sufficient 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 the 'question' property and five aliases, all thoroughly documented. The description provides example questions but no additional parameter-level detail beyond what the schema already states. Baseline of 3 is appropriate since the schema carries the parameter semantics.

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

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

The description clearly states the tool's purpose: answering factual questions by routing to 5,529 tools across 1,455 verified sources, returning structured answers with citations. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research for specific use cases, making its unique role evident.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and step-up instructions for alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. Includes trigger phrases and concrete examples, making when-to-use unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context beyond this: experimental routing candidates, current inactive state, and that it is a full working router with no fallback. This informs the agent about the tool's nature and reliability.

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

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

Description is three sentences, each carrying specific information: beta identity, current state, usage instruction, and fallback clarification. Slightly verbose but well-structured and front-loaded with the key fact that it's a beta version.

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

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

Given the lack of an output schema, the description compensates by pointing to ask_pipeworx's response shape. It also clarifies the tool is fully functional, not a fallback, and explains the comparison workflow, making it sufficiently complete for an AI 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?

Input schema covers all 6 parameters with descriptions, including the 'question' parameter and its aliases, giving 100% coverage. The description cross-references 'same arguments' as ask_pipeworx, but adds no new semantic detail beyond the schema. 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 identifies this as the beta version of ask_pipeworx, stating it is an identical universal router with the same 5,529 tools and response shape. It explicitly contrasts with the stable ask_pipeworx sibling, making its purpose distinct and specific.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that it currently matches ask_pipeworx exactly, implying it's safe to use now. However, it doesn't explicitly state when not to use it (e.g., for stability-critical tasks), so I deduct slightly.

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, destructiveHint=false. Description adds significant behavioral detail beyond annotations: the exact return structure including refusal reasons, the 'using ONLY what the tool result contains' constraint, and the extra LLM call cost. 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?

Every sentence earns its place: purpose, mechanism, return contract, refusal reasons, usage guidance, and cost tradeoff are packed into a compact paragraph. Front-loaded with the core differentiator and ends with actionable preference. No redundancies.

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

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

Given the tool's complexity (routing across 5,529 tools, extraction, refusal handling) and the absence of an output schema, the description is remarkably complete. It specifies return fields, refusal reason enums, and when to choose this tool over the cheaper sibling, covering all key decision factors.

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 only true parameter is 'question' with aliases fully documented. Description doesn't add parameter-level details beyond schema, but the schema is sufficient. Baseline 3 is appropriate because the description context subtly reinforces that the question is natural language, but doesn't add syntax or formatting guidance.

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

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

Description opens with 'Hallucination-resistant answer mode for high-stakes reads,' establishing a specific verb+resource+differentiator. It distinguishes from sibling ask_pipeworx by explicitly contrasting grounded extraction vs. normal mode, and mentions the exact routing behavior.

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

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

Provides explicit when-to-use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also gives an alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups,' and notes it shares routing with ask_pipeworx.

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

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

Discloses extensive behavioral details beyond annotations: resolution process, fan-out per classifier, response shapes, safety mechanisms (low-confidence blocking, closed market handling), resolver contract, parent event extraction, and resolution-rule risk. No contradiction with annotations.

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

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

The description is very long and dense, containing extensive details and examples. While structured with sections, it could be more concise. Some information (e.g., detailed fan-out examples) could be streamlined without losing clarity.

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

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

Given no output schema, the description thoroughly explains return values (market, analysis, evidence, etc.) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). It covers all necessary aspects for an agent to understand and use the tool.

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

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

Schema coverage is 100%, but the description adds significant context: explains market parameter flexibility, depth parameter behavior (quick vs thorough), and include_raw purpose. This goes beyond the schema descriptions, providing practical usage guidance.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific verb 'research' and resource 'Polymarket bet'. It distinguishes from sibling tools like polymarket_edges by focusing on single market research with comprehensive data fan-out.

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

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

Provides explicit usage examples ('should I bet on X', 'what does the data say about Y') and input formats (slug, URL, question). Does not explicitly exclude alternatives but the context and detail clearly indicate when to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations, such as the multiplier logic, ISO 4217 codes (plus XAU/XDR), and that rates are RON per multiplier units.

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

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

Three sentences pack all essential information: source, content, format, multiplier, and currency codes. No fluff 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 no input parameters and no output schema, the description sufficiently explains the output format and nuances (multiplier, ISO codes). Completeness is high for a simple data retrieval 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?

No parameters exist (0 params, schema coverage 100%), so baseline is 4. The description adds meaning about the output structure: reference date, array of currency rates, multiplier details, and currency codes.

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

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

The description clearly states the tool returns the latest BNR official FX reference rates, parsing from BNR's daily XML feed. It specifies the source, content, and format, distinguishing it from siblings like bnr_exchange_rates_history.

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 implicitly indicates use for current rates but does not explicitly mention when to use this vs alternatives (e.g., bnr_exchange_rates_history for historical rates). No when-not guidance is provided.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds context about parsing XML, the return structure (array of daily entries), the rate calculation formula, and that the currency set varies across dates. 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 five sentences, front-loaded with purpose, then behavior, then return format, then rate explanation, then note on currency variation. 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 thoroughly explains the return format (array of objects with date and rates array) and the rate calculation. It also notes that the currency set can vary, which is important for consumers. With only two optional parameters, the description covers all necessary 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% for both parameters. The description adds clarity: explains default behavior (last 10 business days) and overrides (year ignored if year is set). It also provides examples of valid inputs.

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

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

The description clearly states the tool returns historical BNR FX rates, parsed from XML. It specifies the verb 'returns' and resource 'historical BNR rates', and the name 'bnr_exchange_rates_history' distinguishes it from the likely current-rate sibling 'bnr_exchange_rates'.

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 explains when to use no arguments or 'period=10days' for recent data, and when to use 'year=YYYY' for full-year data. It does not explicitly contrast with sibling tools, but the historical focus is clear.

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

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

Adds significant context beyond annotations: specifies data sources (SEC EDGAR/XBRL, FAERS), handles off-calendar fiscal years, and mentions sorting and citation URIs. No contradiction with annotations.

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

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

The description is moderately concise for the amount of information, front-loading trigger phrases and key details. Some details (e.g., off-calendar handling) are valuable but slightly verbose.

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

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

Given the tool's complexity (two entity types, multiple metrics) and lack of output schema, the description covers data pulled, sorting, citation URIs, and efficiency claims, making it self-contained 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 coverage is 100%. The description adds meaning by explaining what data is pulled for each type (company metrics vs drug counts) and the format of values (tickers vs drug names), going beyond the schema descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 entities (companies or drugs) with explicit trigger phrases like 'X vs Y'. It distinguishes from siblings by advocating preference over sequential single-pack lookups (e.g., entity_profile).

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 context is explicit: use for comparisons instead of sequential lookups, with specific query patterns provided. However, it does not explicitly mention when not to use it or list alternatives, though the preference is clear.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses account requirements, latency expectations, output packet structure, gap handling, contradictions, citation_uri fetchability, and semantic excerpting. This adds substantial behavioral context absent from the structured metadata.

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

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

The description is lengthy but information-dense, with the most critical warnings (account required, alternative for unsigned-in users) front-loaded. Every sentence provides useful detail, though the prose is dense and could benefit from more structured formatting. 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?

The description covers prerequisites, alternatives, output format, edge cases (breaking news yielding gaps), depth semantics, latency, and citation fetchability. Despite lacking an output schema, it enumerates the findings packet fields and gap behavior, making the tool's behavior fully interpretable.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter meaning by detailing depth behaviors ('standard' re-angles gaps, 'thorough' chases leads) and clarifies that the question can be broad/multi-part ('decomposition is the point'). This adds significant value beyond the schema.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with decomposition into facets and parallel routing. It distinguishes from open-web search and from the sibling ask_pipeworx, making the purpose unambiguous.

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

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

Explicit usage guidance is provided: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also names the best use cases: 'Best for broad/multi-part questions over structured data'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds context: results are 'ready to call directly, no second schema lookup needed'. 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: first describes purpose and domains, second details return value and usage advice. Efficient, front-loaded, no wasted words.

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

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

Despite no output schema, description adequately describes return format (tool names, descriptions, schemas) and gives usage context. Input parameter behavior is fully covered. Slight gap: no mention of pagination or sorting of results.

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

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

Schema coverage is 100%; parameters are well-described in schema. Description adds value by providing natural language examples and summarizing aliases, but does not significantly go beyond schema.

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

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

Description clearly states 'Find tools by describing the data or task' and lists diverse domains, distinguishing it from sibling tools. It explains return value (top-N relevant tools with schemas) and how to use results.

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

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

Explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Effectively tells when to use and implies 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 annotations (readOnlyHint, idempotentHint, etc.), the description details the data sources fanned out across (SEC EDGAR, XBRL, USPTO, news, GLEIF) and the specific fields returned, including a sunset warning for patents and a fallback mechanism for news. 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 single paragraph is information-dense and begins with concrete examples. It efficiently communicates purpose, usage, and behavioral details without excessive verbosity, though slight restructuring could aid readability.

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

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

Given no output schema, the description adequately explains the return fields (cik, filings, fundamentals, patents, news, LEI) and limitations (patents sunset, name restriction). It covers what an agent needs to know to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that 'type' is limited to 'company', and 'value' accepts ticker or zero-padded CIK, with examples and a note that names are unsupported, referencing a sibling tool. This goes beyond the schema descriptions.

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

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

The description clearly states the tool retrieves a full cross-source profile of a US public company in one call. It includes concrete example queries and explicitly distinguishes it from chained individual lookups, making the purpose unambiguous.

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

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

The description provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use the tool (if only a name is available) and directs to resolve_entity 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 provide destructiveHint and idempotentHint. Description adds context about clearing sensitive data but does not contradict annotations. No annotation contradiction.

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

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

Two sentences, front-loaded with purpose, no wasted words.

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

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

The description is complete for a simple deletion tool given one parameter, annotations present, and no output schema.

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

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

Schema coverage is 100% with a clear description for the single parameter 'key'. Description adds no extra semantics beyond 'by key'.

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

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

The description clearly states the action 'Delete a previously stored memory by key' and distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Explicitly states when to use: 'context is stale, task is done, or you want to clear sensitive data'. Also suggests pairing with alternative tools.

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

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

Annotations already indicate safe, idempotent, non-destructive behavior. The description adds that it fetches the page, extracts title/description/key links, and outputs standard llms.txt markdown, providing useful behavioral context beyond annotations.

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

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

Two sentences that are front-loaded with purpose, followed by details and use cases. 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?

Despite no output schema, the description explains the output format (single text blob) and covers behavior, usage, and purpose completely for a simple tool.

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

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

Schema coverage is 100%, and the description does not add significant meaning beyond the schema's parameter descriptions. 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 it generates a production-ready llms.txt file for any URL, using specific verbs like 'generate' and 'emits'. It differentiates from siblings like scan_competitor_ai_presence by focusing on file generation rather than scanning or analysis.

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 use cases: getting a client's site indexed, drafting for own project, auditing competitors. This provides clear context for when to use the tool, though it lacks explicit when-not scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds return fields and scope (caller's subscriptions), but does not disclose new behavioral traits beyond annotations.

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

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

Two sentences conveying purpose, return values, and usage context with zero waste. Efficiently 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 rich annotations, schema with 100% coverage, and no output schema, the description fully explains return fields and usage scenarios. Complete for a list tool.

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

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

Schema coverage is 100% with a clear description for the 'include_inactive' parameter. Description does not add extra semantics beyond what schema provides, so baseline 3.

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

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

Clearly states it lists active subscriptions with specific return fields, and distinguishes from siblings (subscribe/unsubscribe) by mentioning its use for review before adding or canceling.

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

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

Explicitly says to use for reviewing monitoring before adding more or to find an ID to cancel, providing clear context. Does not include when-not-to-use, but the 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 all-false annotations, the description richly discloses behavior: anonymous submissions return a claim_token for later status checks, the team reads digests daily, rate limit is 5 per identifier per day, and it is free/does not count against quota. It also warns against pasting end-user prompts, adding practical behavioral context.

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

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

The description is long but every sentence carries essential operational information: purpose, use cases, exclusions, token mechanics, rate limits, and cost. It is front-loaded with the core purpose and organized logically, so length is justified by completeness rather than redundancy.

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

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

For a 4-parameter, 0-required, nested-object tool with no output schema, the description covers everything an agent needs: when to use, what to include, token follow-up, rate limits, and scope boundaries. It is fully self-sufficient and complement the schema without repeating 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%, so the baseline is 3, but the description adds real value beyond the schema: it explains the claim_token follow-up invocation pattern (pipeworx_feedback({claim_token:"pwfb_…"})) and instructs describing issues in terms of Pipeworx tools/packs, which meaningfully informs how to fill context and message. Slightly less value is added to the type and context parameters because the schema already defines them well.

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

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

The description opens with a clear, specific verb+resource statement ('Tell the Pipeworx team something is broken, missing, or needs to exist') and immediately distinguishes the tool from siblings by enumerating feedback types (bug, feature/data_gap, praise). It is unmistakably a feedback submission tool, not an ask or research tool.

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

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

Provides explicit when-to-use guidance for each feedback type and a strong when-not-to-use exclusion: if the tool came from a different MCP server, file with that server instead. It even offers a disambiguation rule ('Pipeworx tool names are the ones this connection lists'), making selection unambiguous.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral details: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This clarifies data provenance, privacy, and freshness beyond what annotations offer.

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

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

The description is concise (5 lines) with well-structured bullet points for use cases. Every sentence adds value, no fluff. It front-loads the core functionality and then provides context.

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

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

For a tool with 1 optional parameter and no output schema, the description is remarkably complete. It covers purpose, parameters, use cases, data source, caching behavior, and privacy (no PII). No gaps remain for the agent to make informed decisions.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic nuance for the 'window' parameter: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides actionable guidance on choosing window values.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('Returns') and resource ('trending data on Pipeworx'), and distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on aggregate usage data across agents.

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 concrete use cases (e.g., discovering hot data sources, confirming canonical choices, aligning use cases). It provides context for when to use each window. However, it does not explicitly state when not to use the tool or mention alternatives, though the unique nature of the tool makes this less critical.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint false, consistent with a scanning tool. The description adds significant behavior: explains internal checks (partition_check, fill_check), semantic anchor, partition filter, and response structure. No contradiction with annotations; it provides rich context 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 front-loaded with purpose and structured by mode. While verbose (details on partition_check and fill_check), it remains well-organized. Every sentence adds value, but slight trimming could improve conciseness without loss of clarity.

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

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

Despite no output schema, the description details the return format (opportunities[] with fields, partition_check object) and edge cases (skipped_low_similarity, placeholders_filtered). It references sibling tools for further detail. For a complex arbitrage tool, this is comprehensive and leaves minimal ambiguity.

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

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

Input schema describes both parameters with 100% coverage, but the description adds meaning by explaining how each parameter affects the mode (event slug, topic seed) and that full URLs are accepted for event. This extra context enhances understanding beyond the schema alone.

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

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

The description starts with a clear statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection with specific algorithms.

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

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

The description provides explicit guidance: 'Call with NO args for a trending_scan,' 'event (recommended for a specific market),' and 'topic (for cross-event scanning).' It also warns when not to trade: 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' References polymarket_fill_risk for custom sizing, clearly indicating alternative tools.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds extensive behavioral details including caching strategy (1h KV cache keyed on knobs), model formulas for each segment, diagnostics for empty segments, and exclusion of Fed candidates due to unreliable signals. No contradictions with annotations.

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

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

The description is well-structured with front-loaded purpose and clear segment breakdowns, but it is verbose, containing detailed model formulas and specific parameter values that could be condensed. While informative, it could be more concise without losing essential guidance.

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

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

Given the tool's complexity (9 parameters, three segments, no output schema), the description is exceptionally complete. It explains the response structure (by_segment, fed_candidates, _diagnostics), details each opportunity's fields (edge_pp_net, kelly_fraction, market liquidity, etc.), and clarifies edge cases like Fed candidates and caching behavior.

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

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

All 9 parameters have 100% schema description coverage, meeting the baseline for high coverage. The tool description adds value by explaining the 'tradeable-edge knob' concept and how parameters like min_kelly, min_liquidity, and min_partition_leg_kelly interact across the three segments, providing context beyond individual parameter descriptions.

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

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

The description clearly states that the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, specifically built for 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on comprehensive scanning across multiple model families.

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 that the tool is for discovering opportunities without paging hundreds of markets, and explains the three segments and configurable knobs. However, it does not explicitly state when to use this tool versus its siblings or provide when-not-to-use guidance.

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

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

The description enriches the readOnlyHint and idempotentHint annotations by detailing snapshot behavior, 60-day TTL, decay computation from |edge_pp_net|, and the meaning of trend and decay_pp_per_day. It also explains snapshot gaps and output structure, far exceeding what annotations alone 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 lengthy but well-organized: purpose first, then output fields, then limits. Every sentence adds necessary detail, and the front-loading helps agents quickly grasp the tool's function. It could be slightly more concise but is justified given the complexity.

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

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

Despite lacking an output schema, the description thoroughly explains the three output arrays (tracked, expired, snapshot_dates) and their fields, plus limits like 60-day TTL and decay calculation. This fully compensates for the absence of a structured schema.

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

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

Schema coverage is 100%, but the description adds default values (14 days, '1wk'), clamping (2-30), and explains how parameters affect the response (e.g., days lookback). This adds value beyond the 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 it provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes this from the sibling tool polymarket_edges by focusing on historical trends rather than current edge values.

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

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

The description implies use cases via the contrast between fresh and old edges, and the output structure (tracked vs expired) gives context for when to use. However, it does not explicitly state when not to use or name alternatives, so it lacks full exclusion 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?

Description adds significant behavioral context beyond annotations: explains what the tool does internally (walk the ladder, return specific fields), highlights risks (thin books, partial fills leading to unhedged positions), and confirms it is a read-only, idempotent check. 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?

Description is thorough but slightly verbose; it front-loads the main purpose and uses structure (caps, section headers) for clarity. Every sentence adds value given the tool's complexity, but could be tightened slightly.

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

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

Covers both modes comprehensively, lists all return fields, explains edge cases (thin legs, forced directional risk), and provides reasoning for use. Without an output schema, the description fully documents expected outputs and risks.

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 enriches parameter meaning by explaining how size_usd is interpreted differently in single-market vs. basket mode, the default logic for side in basket mode, and the distinction between market and event parameters. This goes well beyond the schema descriptions.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check using live order-book depth, and distinguishes between single-market and basket modes. It explicitly differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges by advising when to use 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?

Explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale and warns against skipping it for thin books or partial fills, providing clear usage context.

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

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

Discloses extensive behavioral details beyond annotations: response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and counters (skipped_cross_type). Explains failure modes like temporal misalignment and non-equivalent bet shapes. No contradiction with readOnlyHint=true.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the purpose. While thorough, it is slightly verbose in the safety fields section; could be trimmed slightly.

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

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

Given the tool's complexity (two venues, multiple parameters, safety fields) and no output schema, the description is highly complete. It covers all relevant aspects: modes, response, edge cases, and warnings.

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

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

All three parameters are fully described in the schema. The description adds meaning by explaining the purpose of each mode, providing example values for topic (enum list), and clarifying that explicit parameters override topic mapping.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket. It specifies two modes (pre-mapped topics and explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage which focus on intra-venue spreads.

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

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

Provides explicit guidance on when to use each mode and warns that pre-mapped topics often return compatibility warnings, indicating limited tradeability. However, it does not contrast with alternatives like polymarket_arbitrage for intra-venue arbitrage.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds that results are scoped to user identifier and explains behavior when key is omitted, which is beyond annotations.

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

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

Two sentences, front-loaded with action, no wasted words.

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

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

Simple tool with one optional parameter and no output schema; description fully explains purpose, usage, and scope.

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

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

Schema coverage is 100% and description adds no new parameter details beyond restating schema meaning. Baseline 3 is appropriate.

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

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

Description clearly states verb (retrieve/list) and resource (saved memory), differentiates two modes (by key or list all), and distinguishes from siblings remember and forget.

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

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

Explicitly says when to use (look up stored context) and pairs with remember/forget. Lacks explicit when-not-to-use but scope and alternatives are covered by context.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds that setting mark_read:true flags events as read, affecting subsequent calls. It also details return fields (source, citation_uri, raw payload). 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 4 sentences, front-loaded with purpose, and every sentence adds value. No redundant or vague statements. Efficient and clear.

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

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

Given 5 optional parameters, no output schema, and rich annotations, the description covers key behavioral aspects (polling, mark_read effect, return structure). It could mention limit and unread_only more explicitly, but overall provides sufficient context 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?

All 5 parameters are described in the schema. The description adds usage context for type (example 'sec_8k'), since (ISO timestamp), and mark_read (flag to affect future calls). This goes beyond the schema's basic descriptions, enhancing agent understanding.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying it returns recent alerts. This distinguishes it from sibling list_subscriptions (which lists subscriptions, not alerts). Verb 'pull' and resource 'fired events' are specific.

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 context for when to use the tool (polling) and mentions an alternative (GET registry.pipeworx.io/alerts.json for scripts/dashboards). It does not explicitly state when not to use, but the guidance is clear enough for an agent.

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

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

Despite annotations already marking readOnlyHint, idempotentHint, etc., the description adds rich behavioral detail: fan-out to multiple sources, fallback logic, soft-fail for USPTO, return structure with grouped changes and citation URIs.

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?

Efficiently front-loaded with usage examples, every sentence adds value. Slightly long but justified by complexity of multiple data sources; would not cut any 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?

Fully covers all aspects: parameters, source behavior, fallback, return structure, and sibling differentiation. No output schema needed because description adequately explains outputs.

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

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

Schema coverage is 100%, but description adds substantial meaning: explains 'type' is restricted to 'company', provides examples for 'since' (ISO and shorthand), and clarifies 'value' accepts ticker or zero-padded CIK. Goes beyond schema.

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

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

The description clearly states the tool provides a change feed for a company, with specific query examples ('What's new with X', 'latest on Y') and explicitly distinguishes from sibling 'entity_profile' for static profiles.

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

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

Provides explicit when-to-use (queries about recent updates) and when-not-to-use (static profile, refer to entity_profile). Also explains fallback behavior between GDELT and GNews.

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

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

Annotations already indicate idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds meaningful context: scoped by identifier, persistence differences between authenticated users (persistent) and anonymous sessions (24 hours), and pairing with other tools. No contradiction. Slightly better than baseline due to extra detail.

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

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

The description is four sentences, each serving a purpose: first states the core function, second gives usage context, third explains scope and persistence, fourth mentions pairing. No fluff. Optimally concise.

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

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

Given the tool's simplicity (2 parameters, no output schema) and rich annotations, the description covers all necessary aspects: purpose, usage, storage behavior, and integration with siblings. It is fully complete for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100% with clear descriptions for both key and value. The description adds value by giving example keys ('subject_property', 'target_ticker', 'user_preference') and value types ('findings, addresses, preferences, notes'), but does not substantially go beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with specific verb (Save) and resource (data). It distinguishes from siblings by mentioning 'Pair with recall to retrieve later, forget to delete.' This meets the highest standard.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference, research subject). It also clarifies when not to use by noting the pairing with recall and forget. This is exemplary.

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 discloses that unresolved identifiers are reported under `unresolved`, LEI/FIGI enrichment degrades gracefully with EDGAR still returning, and each call cascades through multiple endpoints. These are valuable, non-obvious behaviors.

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 typical but well-structured, leading with example queries, then core purpose, supported types, and fallback behavior. Every sentence carries functional information, though a slight trim would improve conciseness without losing 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 thoroughly compensates by listing returned identifiers, source labels, unresolved handling, and graceful degradation. It is complete for a tool with two entity types and complex internal lookups.

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 both parameters fully described including examples. The description reinforces the schema with additional context (e.g., source systems for each type) but does not significantly add syntactic or formatting details 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 resolves user-spoken names to canonical/official identifiers, with specific verb+resource and supported types. It distinguishes from siblings like entity_profile/compare_entities by emphasizing 'Use FIRST whenever you have a name but need 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?

Explicitly instructs to 'Use FIRST whenever you have a name but need an ID' and provides query examples. It does not name alternative tools or conditions to avoid using this tool, but the supported types and the note that it replaces 2-3 manual lookups provide clear context.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds beyond this: it explains that each entity is probed with ai_visibility_check, results are ranked by score, and it surfaces most/least recognized. It also details the return format (ranked list with score, confidence, signal density). No contradictions.

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

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

Three sentences, all value-adding. The first sentence immediately states the core function. No verbose or redundant text. Every sentence earns its place.

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

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

Without an output schema, the description sufficiently explains the return value (ranked list with score, confidence, signal density). It covers the tool's purpose, usage, and key parameters. A small gap is the lack of mention of the optional 'models' parameter's effect on results, but overall it is complete 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 coverage is 100% and descriptions are provided. The description adds marginal value: it notes the first entity is treated as 'subject', and context disambiguates common names. However, these are already implied or described in the schema. Baseline 3 is appropriate as the description does not significantly enhance schema parameters.

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

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

The description uses specific verbs ('Compare', 'Probes', 'ranks') and clearly identifies the resource ('AI visibility across multiple entities'). It differentiates from sibling tool ai_visibility_check (single entity) and implies comparison versus general compare_entities. The example question clarifies the exact 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 explicitly states when to use: for competitive AI-marketing audits. It provides an example question and mentions the tool compares multiple entities. While it doesn't explicitly list exclusions, the context signals and sibling tools suggest alternatives. The description is clear enough for agents to select correctly.

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

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

Discloses timing behavior: bundlephobia's first measurement takes 5-30s, and sources_failed will list it if timeout. Annotations already indicate readOnly, openWorld, idempotent, non-destructive; description adds practical context about failure handling without contradiction.

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

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

Three sentences: first defines composite purpose, second gives usage and scope, third describes output and failure mode. Front-loaded with most important information; no wasted words.

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

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

Covers all needed context: composite nature, data sources, output fields, ecosystem scope, version default, and partial failure behavior. No output schema, but description lists all return fields (summary, advisories, links, alternatives). Complete for a tool of this complexity.

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

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

Schema provides full coverage (2 params, both described). Description adds: scoped packages accepted for 'package', and 'version' defaults to latest. Baseline 3, plus extra details justify 4.

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

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

Description clearly states it's a composite check for npm packages, combining deps.dev and bundlephobia data. Starts with a clear verb-resource pair: 'should I add this npm package' check. Distinguishes from sibling tools by focusing on npm ecosystem evaluation.

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

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

Explicitly tells when to use ('when agent asks is X safe/popular/small' or 'what does adding lodash cost me') and when not (NPM only; other ecosystems use deps.dev directly). Also mentions graceful degradation for partial failures.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars with truncation flag), and that passages include offsets for verification. No contradiction.

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

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

The description is concise (four sentences) and well-structured. The first sentence states the core purpose. Subsequent sentences add precision, use cases, and technical details. Every sentence earns its place with 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?

Given no output schema, the description adequately explains return values (passages with offsets and scores). It covers all necessary context: when to use, how it works (embeddings, windows, cap), pairing with sibling tool, and limitations (200K char cap). The description is complete for an effective tool.

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

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

Schema coverage is 100% with three parameters. The description adds meaning: for 'text' it specifies max length and purpose; for 'query' it provides natural-language examples; for 'limit' it gives range (1-20) and default (5). This context helps the agent select appropriate values beyond schema descriptions.

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

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

The description clearly states the tool's function: semantic search inside a fetched record. It specifies the inputs (text and natural-language query) and outputs (top-N passages with offsets and scores), and distinguishes it from siblings by mentioning 'ask_pipeworx_grounded' and explaining how they pair.

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: 'when the record is too big to cram into the prompt.' It also provides guidance on pairing with 'ask_pipeworx_grounded,' and contrasts with alternatives by stating it saves context and returns only relevant passages.

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

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

Discloses behavioral traits beyond annotations: requires OAuth account, returns subscription id, delivery limitations (SMS cap, phone verification, webhook auto-disable after 10 failures). No contradiction with annotations.

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

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

Well-structured with bullet points and examples, but slightly long. Front-loaded purpose, then detailed examples. Could be more concise but effective.

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

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

Complete for a subscription creation tool: covers all params, requirements, limitations, and return value. No gaps given schema coverage and no output schema.

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

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

Adds significant meaning beyond schema: provides detailed examples for each type's params (e.g., sec_8k items codes, polymarket_edge topic) and explains delivery sub-parameters including webhook signing secret.

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 and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

Explicitly states when to use (proactive monitoring) and prerequisites (requires Pipeworx OAuth account). Provides supported types and delivery channel details, but does not explicitly mention alternative tools for one-off queries.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral detail: it returns questions drawn from a live catalog, explains topic effect, and mentions it's for learning meta-tools. No contradictions.

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

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

Description is front-loaded with natural language questions but is slightly long. Every sentence earns its place, but could be tightened slightly without losing clarity. Well-structured.

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

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

Despite no output schema, description thoroughly explains the return value (category-bucketed example questions with tool/argument shapes) and how to use topic. Covers all necessary context for a simple onboarding tool.

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

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

Schema coverage is 100% with a description for the topic parameter. Description adds significant value: lists example topics, explains effect of omitting, and provides context beyond schema (e.g., 'finance', 'pharma'). Fully compensates.

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

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

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

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

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

Explicitly tells when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains optional topic parameter for focus, guiding appropriate use.

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

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

Beyond annotations, the description reveals key behavioral traits: the row is deactivated (not deleted), and historical events remain accessible via recent_alerts. This adds context about the non-destructive nature and data retention, aligning with 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 extremely concise (two sentences) and front-loaded with the core purpose. Every sentence adds essential information with no redundancy.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description covers all necessary aspects: purpose, ownership, behavior, and outcome. 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 single parameter 'id' is fully described in the schema (100% coverage). The description adds minor value by noting the id comes from the subscribe tool, but does not elaborate beyond the schema's description.

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

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

The description clearly states the verb 'Cancel' and the resource 'a subscription by id'. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions', and adds specifics about ownership and deactivation.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), which guides appropriate use. It also explains the deactivation behavior but does not explicitly contrast with alternative tools for managing subscriptions.

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

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

The description goes far beyond the annotations. It discloses the internal routing logic, the exact verdict types returned, the presence of citations, and the crucial error semantics (could_not_verify means the check did not happen and must not be shown as evidence). This aligns with the readOnlyHint and idempotentHint annotations without contradicting them.

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

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

The description is long but well-structured. It starts with natural-language examples, then defines purpose, explains internal paths, and covers return values and error handling. Every section serves a purpose, though some phrases (e.g., the list of example phrasings) could be trimmed without losing essential information.

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

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

There is no output schema, so the description fully specifies the return shape (verdict, value, citation, reasoning) and error modes. It also covers both structured and grounded claim paths, making the tool self-contained and reducing the need for the agent to infer behavior from the schema or annotations alone.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful nuance for tolerance_pct by explaining it overrides the claim-wording implied tolerance and suggesting 1-2% for hallucination detection. The claim parameter is already well-described in the schema, so the added value is moderate but useful.

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 ('validate', 'verify', 'fact check') and clearly identifies the resource (natural-language claims against authoritative sources). It distinguishes itself from sibling tools like ask_pipeworx and deep_research by focusing on claim verification, and even notes that it replaces 4-6 sequential calls.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two internal paths (SEC EDGAR/XBRL for company-financial claims, grounded pipeline for others), and clarifies the meaning of could_not_verify vs unsupported, giving the agent clear guidance on how to interpret and use the result.

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