Eu Parliament

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint false. Description adds that it probes LLMs, returns per-model scores with confidence/signals/raw_response, and combined view. No contradictions. Adds useful behavioral detail 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?

Four concise sentences, no wasted words. Front-loaded with the core action and scoring, followed by defaults, return format, and use cases. Perfectly sized.

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 return structure (per-model {score, confidence, signals, raw_response} + combined view). All parameters are covered, and use cases are given. Complete for the tool's complexity.

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

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

Schema coverage is 100% with good parameter descriptions. Description adds context about default model (Workers AI Llama-3.3-70b free), BYO key for Anthropic, and payment model, which enriches understanding beyond 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 uses a specific verb ('Probe'), resource ('LLMs'), and scope (business/brand/product/topic, score 0-100 per model). It clearly distinguishes from siblings by focusing on AI visibility scoring, not general Q&A or research.

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

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

Explicitly states use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to provide _apiKey for Anthropic. Lacks explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that: routing to 5,529 tools, filling arguments, returning structured answers with stable pipeworx:// citation URIs, and being the default entry point that works on every tier. This is helpful, though it doesn't detail edge behaviors like error handling or rate limits, so it doesn't earn a 5.

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 exceptionally well-structured: it starts with the core directive, lists covered domains, explains the mechanism, provides trigger phrases, gives multiple examples, states prioritization, and then contrasts with alternatives. Every sentence earns its place, and the structure makes it easy to scan. This is concise for the amount of critical guidance it delivers.

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 question-answering tool with no output schema, the description is comprehensive: it explains what the tool does, when to use it, what it returns (structured answers with citations), and how it fits among siblings. Combined with the informational annotations, it provides enough context for an agent to select and invoke it correctly without confusion.

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

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

The input schema has 100% coverage: all six parameters are described as aliases for 'question', and the primary parameter has a solid description explaining natural language input with aliases. The description adds examples of valid questions, but no additional parameter semantics beyond the schema. This matches the baseline of 3 for high schema coverage.

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

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

The description clearly states that this tool answers factual questions by routing to thousands of verified sources and returning structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by explicitly recommending those for different use cases, making its purpose and scope unmistakable.

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

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

The description provides extensive usage guidance: it declares when to prefer this tool over web search, lists triggering phrases, gives concrete examples, and explicitly names alternatives with conditions (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions). It also clarifies when it is already the right choice for breaking news. This goes far beyond basic 'when to use' guidance.

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

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

The description goes beyond the annotations by disclosing the experimental nature: it may have routing improvements enabled live, but currently no candidate is active, so it matches ask_pipeworx exactly. It also notes that results are compared for merge decisions and that there is no fallback. This adds behavioral context that annotations (readOnly, idempotent, etc.) do not cover, such as potential future changes and current state.

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

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

The description is a compact paragraph of four sentences, with each sentence serving a distinct purpose: defining the beta, stating current active state, giving usage guidance, and clarifying it's a full router. It is front-loaded with the key identifier 'Beta version of ask_pipeworx' and contains no redundant phrases. Slightly longer than the two-sentence ideal, but still efficient for 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?

Given the tool's complexity (a router with 5,529 underlying tools) and no output schema, the description adequately covers what an agent needs: what it does, how it differs from the stable version, current behavior, and usage. It explicitly states the response shape is identical to ask_pipeworx, which serves as a substitute for a detailed return specification. The description is complete for making an informed invocation decision.

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

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

Schema description coverage is 100%, with all parameters (question and aliases) thoroughly documented in the input schema. The description itself does not add any parameter-specific semantics beyond stating 'same arguments' as ask_pipeworx, which is not additional detail. Given the high schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,529 tools and arguments. It explicitly differentiates from the stable version by highlighting the experimental routing improvements, thus distinguishing it from sibling tools like ask_pipeworx and ask_pipeworx_grounded.

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

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

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also contrasts with the stable router, implying when to use the stable alternative, and clarifies that this is a full working router, not a fallback. This directly answers when to use this tool vs. alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the exact success and refusal response shapes, the refusal reason enum, the verbatim evidence inclusion, and the extra LLM call cost. It adds substantial behavioral context without contradicting any annotations.

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

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

The description is dense and front-loaded: first sentence states purpose, then process, then output formats, then usage guidance, then cost tradeoff. Every sentence carries essential information with no redundancy, making it both succinct and 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?

Even though there is no output schema, the description fully specifies both success and refusal response structures, including fields and refusal reasons. It also covers use cases, cost implications, and fallback behavior, making the tool's behavior completely anticipatable.

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

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

The schema already fully documents the 'question' parameter and all aliases with 100% coverage. The description adds no additional parameter-specific meaning beyond general behavior, so it meets the baseline but does not exceed it.

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

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

The description clearly states it is a 'hallucination-resistant answer mode' that extracts answers using only tool results. It distinguishes itself from the sibling 'ask_pipeworx' by explaining the grounded answer and refusal behavior, making its purpose specific and unique.

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 when an answer will be quoted, cited, or acted on, and when facts must not be invented, listing examples like financial verdicts and legal claims. It also provides a clear alternative: 'prefer ask_pipeworx for casual lookups' due to the extra cost, naming the sibling 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 cover read-only, idempotent, destructive false. The description adds extensive behavioral details: low-confidence resolution short-circuit, closed market status, wide-spread tradeability note, cancellation rule parsing, resolver contract, parent event extractor, news field fallback. This is exemplary transparency well beyond the annotations.

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

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

The description is long but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and examples. It front-loads the core purpose. While somewhat verbose, every sentence adds value given the tool's complexity. Minor reduction in length could improve readability.

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

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

Despite no output schema, the description provides an exceptionally complete picture: input modalities, processing steps (classification, fan-out), response structure, edge cases (low confidence, closed markets, wide spreads, cancellation rules), and fallback behavior for news sources. No gaps identified.

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

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

Schema coverage is 100% for all 3 parameters. The description adds significant value beyond schema: explains market input variants (slug, URL, question text), depth options with tradeoffs (quick vs thorough), and include_raw consequences (summary vs full payload size). This enriches the schema descriptions meaningfully.

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

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

The description opens with a specific verb+resource combination ('Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call') and clearly defines the tool's scope. It distinguishes itself from siblings by focusing on a single bet research with fan-out data, which is not covered by other Polymarket-related tools (arbitrage, edges, etc.). The use cases ('should I bet on X', etc.) are explicitly stated.

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

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

The description provides clear context for when to use the tool (specific questions about betting on Polymarket) and implies usage through the fan-out examples and classifier list. However, it lacks explicit exclusions or comparisons with sibling tools, which would elevate it to a 5. Still, it is sufficient for an agent to understand its role.

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 valuable context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with trigger phrases. It is relatively concise for the amount of information conveyed, though it could be slightly more structured (e.g., bullet points for data types). Every sentence adds value.

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

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

Given the complexity of the tool (comparison with multiple entities, different types, data sources), the description is comprehensive. It explains the return format (paired data + citation URIs), sorting behavior, and replaces many sequential lookups. No output schema exists, but description covers key output aspects.

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 adequate descriptions for both parameters. The description adds meaning beyond the schema by explaining what data each type returns (e.g., for 'company': revenue, net income, cash, long-term debt; for 'drug': adverse-event counts, approval counts, trial counts).

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

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

The description clearly states that it performs side-by-side comparisons of 2-5 companies or drugs using specific data sources. It distinguishes itself from sequential lookups and includes trigger phrases like 'compare', 'vs', 'rank these companies'.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and provides concrete examples of when to use (e.g., 'which is bigger', 'head to head'). This leaves no ambiguity about when to invoke 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?

The description goes far beyond annotations by disclosing account requirements, paid tier for thorough, latency expectations (15-60s, up to 90s), decomposition behavior, gap[] handling ('never invented'), contradiction[] scanning, semantic excerpting, and resolvable citation_uri. These are critical behavioral traits not available from annotations alone.

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

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

The description is long but every sentence earns its place, covering accounts, alternatives, behavior, latency, and output structure. It is somewhat a wall of text without bullet points, but it is front-loaded with the most critical caveats (account required, alternatives). Could benefit from clearer structure, but given the complexity, it is efficient.

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

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

With no output schema, the description fully explains return values: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]' and 'contradictions[]' for standard/thorough. It also covers latency, depth semantics, and alternative tools, making it complete for an agent to use correctly.

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

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

Schema coverage is 100%, and the description largely restates the schema's parameter explanations. The depth behaviors (gap recovery, contradictions scan) are already in the schema's parameter descriptions. The description adds some operational context around latency and account tiers, but not significant new meaning for the parameters themselves, keeping it at the baseline.

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

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

The description clearly states the tool's specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It distinguishes itself from siblings by emphasizing it is NOT open-web search, decomposes questions into facets, and routes to 5,529 tools in parallel. It also contrasts with ask_pipeworx for single lookups, giving it a unique identity.

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

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

Explicit when-to-use and when-not-to-use guidance is provided: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also specifies an alternative if not signed in ('use ask_pipeworx instead'). This is a model example of usage clarity.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds valuable behavioral details: returns 'the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly.' This goes beyond annotations.

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

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

The description is front-loaded with the core purpose and usage guidance. It contains a list of example domains which is helpful but slightly lengthy. Every sentence adds value, and the structure is logical. Could be slightly more concise, but overall well-organized.

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

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

Despite lacking an output schema, the description fully explains what the tool returns ('top-N most relevant tools with names, descriptions, and full input schemas'). It specifies the default and maximum limit, and describes input semantics completely. No gaps remain for effective use.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context that the query parameter accepts aliases (task, q, description, search) and natural language input, but this is already detailed in the schema property descriptions. No significant additional meaning.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example domains and distinguishes from the large set of sibling tools by being the only discovery-oriented tool.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides strong positive guidance, though it does not explicitly state when not to use or mention specific alternatives.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description confirms parallel call, adds details like soft-fail for patents (sunset May 2025), and the specific data sources used. 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 lengthy but every sentence adds meaningful context. It opens with usage examples and then details the multi-source fan-out. While slightly verbose, it is structured effectively with clear sections.

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 enumerates all returned fields (CIK, name, filings, fundamentals, patents, news, LEI) with details like filing URIs and sorting. It also mentions limitations (patents soft-fail, name unsupported). Covers all necessary context for the aggregator 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 descriptions. Description adds value by explaining that value can be ticker or zero-padded CIK, and explicitly warns that names are not supported (use resolve_entity). This extra guidance raises the score above baseline 3.

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

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

The description clearly states the tool aggregates a full cross-source profile of a US public company in one parallel call, listing specific sources and outputs. It distinguishes itself from siblings like compare_entities and resolve_entity by focusing on holistic single-entity profiles.

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

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

Explicitly advises preferring this over chaining separate lookups for a holistic view, and specifies that names are not accepted—use resolve_entity first. Provides clear when-to-use and when-not-to with concrete examples.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description states delete action, which aligns with annotations. No additional behavioral context but no contradiction.

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

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

Two sentences: first defines action and resource, second provides usage guidance. Every sentence is necessary and efficient, no wasted words.

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

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

Given the simple tool (single required parameter, no output schema, annotations present), the description fully covers purpose, usage, and constraints.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to delete'. Description does not add extra semantics beyond what is in the schema, thus 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?

Description clearly states 'Delete a previously stored memory by key' with specific verb (delete) and resource (memory). It distinguishes from sibling tools 'remember' and 'recall', which are mentioned in the description.

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

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

Explicitly says 'Use when context is stale, the task is done, or you want to clear sensitive data' and 'Pair with remember and recall', providing clear when-to-use and related alternatives.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds behavioral details: fetching the page, extracting title/description/key links, and emitting standard llms.txt markdown. This clarifies the exact output and process beyond annotations.

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

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

The description is a concise three-sentence paragraph that front-loads the action and purpose. It includes a bullet-like list of use cases, which is efficient. It is not overly long but could be slightly more structured.

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

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

Given the tool's simplicity, full schema coverage, and rich annotations, the description adequately explains purpose, behavior, output, and use cases. It lacks mention of potential failures or constraints, but overall it is sufficiently complete for an agent to use 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 the baseline is 3. The description does not add extra meaning beyond the schema: it mentions key links but not max_links. The schema already describes max_links's default and max value, so the description adds no additional 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: generating a production-ready llms.txt file for a URL, for AI crawlers. It lists specific use cases (client sites, own projects, competitor auditing), distinguishing it from any sibling tool that might do something similar.

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 useful usage scenarios (getting a site indexed, drafting, auditing), giving clear context. However, it does not explicitly exclude alternative tools or state when not to use this tool, which would improve guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that by default only active subscriptions are returned, with an option to include inactive ones, providing 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, no wasted words. Front-loaded with the core purpose, then details and usage 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?

For a simple listing tool with one optional parameter and no output schema, the description covers purpose, return fields, default behavior, and usage context completely.

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

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

Schema coverage is 100% with a clear description of the boolean parameter. Description reinforces default behavior (active only) but doesn't add significant new meaning beyond the schema.

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

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

The description clearly states it lists the caller's active subscriptions and enumerates returned fields (id, type, etc.). It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises use for reviewing subscriptions before adding more or to find an id to cancel. Lacks explicit when-not-to-use but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false, covering the safety profile. The description adds no new behavioral details (e.g., response format, pagination), so it provides no extra value.

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 (4 words), which is efficient but omits essential information like what an MEP is and the verb (e.g., 'get'). It is front-loaded but under-specified.

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 read-only nature and single parameter, the description minimally meets needs but fails to mention output format (though an output schema exists), nor does it explain the entity. Complete coverage would require at least stating 'Returns details of a single MEP by ID.'

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

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

Schema coverage is 0%, so the description must compensate for the parameter. It only restates 'id' from the parameter name, with no format, constraints, or background. The schema example '124688' is not referenced. This is insufficient for an agent to understand the parameter.

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

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

The description 'Single MEP by id.' indicates retrieval of one MEP entity, with 'MEP' assumed as Member of European Parliament. It is clear but lacks verb specification, and the acronym is not explained, relying on context from sibling tools.

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

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

No guidance on when to use this tool versus its sibling 'meps' (presumably listing multiple MEPs) or other tools. There is no mention of prerequisites or context, making it hard for an agent to choose 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the temporal distinction between "sitting NOW" and historical data via `term`. No contradictions with annotations.

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

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

The description is two short, front-loaded sentences. The first sentence states the core purpose and filters; the second clarifies the historical mode. Every word earns its place, with no redundancy or filler.

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

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

Given the output schema and annotations, the description sufficiently covers the main behaviors: listing current MEPs, filtering by country/group, and switching to historical via term. Pagination parameters (limit/offset) are present in the schema, and the read-only/idempotent nature is annotated. The description is complete for an agent to invoke correctly.

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

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

Schema description coverage is 60%; term, group, and country have detailed descriptions. The description reinforces `term` as the historical toggle and mentions filterability by country/group, but adds little for `limit` and `offset`. The schema carries most of the parameter meaning, so a 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 uses a specific verb+resource: "List the Members of the European Parliament sitting NOW". It clearly distinguishes the tool's scope (current members) and adds the filter dimensions (country, political group) plus an alternate mode via `term` for historical registers. This strongly differentiates it from the sibling tool `mep` (singular).

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

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

The description provides explicit when-to-use guidance: use without `term` for current sitting MEPs, pass `term` for the historical register. It does not explicitly name alternatives like `mep` (singular), but the context is clear enough for an agent to know when this list tool is appropriate.

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

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

The description discloses the claim_token flow, rate limiting ('Rate-limited to 5 per identifier per day'), and cost model ('Free; doesn't count against your tool-call quota'). It also instructs users not to paste end-user prompts, adding behavioral context. Annotations are all false, so the description carries the transparency burden fully and does so thoroughly.

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

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

The description is a single dense paragraph, but it is front-loaded with the core purpose and progressively covers scope, claim_token, and rate limits. Every sentence adds useful information, though the paragraph form slightly reduces scannability; a bulleted structure would earn a 5.

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 explains the claim_token return value and how to follow up. It covers scope, use cases, rate limits, and cost, making the tool fully self-contained. There are no ambiguous or missing behavioral requirements for the 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 100% of parameters, but the description adds crucial semantics for claim_token: 'pass the `pwfb_…` token that filing returned, with no other arguments.' It also reinforces message specificity ('don't paste the end-user's prompt'). While the schema describes each parameter individually, the description enriches the usage semantics beyond field definitions.

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

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

The description opens with a clear, specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It differentiates from sibling research/query tools by explicitly scoping to feedback about Pipeworx tools and contrasting with other MCP servers ('if the tool came from a different MCP server... file it with that server instead'). This leaves no ambiguity about the tool's purpose.

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

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

The description explicitly lists when to use the tool: for bugs, feature/data_gap requests, or praise. It also states a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to file with the other server otherwise. This is strong when/when-not guidance.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. Description adds concrete behavioral context: self-aggregating signal from CF analytics, no PII, caching policy (5min-1h). No contradictions.

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

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

Single paragraph, well-structured with bullet-like numbered list. Slightly verbose ('Self-aggregating signal...') but each sentence adds value. 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?

For a simple tool with 1 optional parameter and no output schema, the description covers purpose, use cases, data source, privacy, caching, and output shape. No gaps.

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

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

Schema provides enum for 'window' with descriptions. Description goes further by explaining trade-offs: 'shorter windows surface what's hot right now; longer windows show steady-state demand'. This adds decision-making context.

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

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

Clear verb+resource: 'Returns the top tools, top packs, and total call volume'. Distinguishes from siblings like 'discover_tools' (which lists all tools) and 'ask_pipeworx' (which answers questions).

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

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

Explicitly lists three use cases (e.g., discovering hot data sources, confirming canonical tool, aligning use case). However, it does not state when not to use or mention alternatives like 'discover_tools' for comprehensive listing.

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, but the description adds no behavioral details (e.g., pagination, ordering, scope). It fails to leverage the opportunity to provide additional 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?

While extremely short, the description is under-specified rather than concise. It omits key information that should be present for a 4-parameter tool.

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

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

Despite having an output schema, the description fails to contextualize the tool's role within the plenary documents domain. With no required parameters and low schema coverage, the description is incomplete for effective tool selection.

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 only 25% (only 'type' has a description). The description does not explain any parameters (term, limit, offset) or their expected values, leaving the agent to infer from the schema alone.

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

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

Description 'Plenary documents' is vague; it restates the name without specifying an action (e.g., list, search) or differentiating from sibling tools. Examples in schema imply retrieval, but the description alone is insufficient.

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?

No guidance on when to use this tool versus alternatives. No context about prerequisites, typical use cases, or exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: how events are processed, semantic anchor for cross-event pairs, partition filter for placeholders, fill check against CLOB depth, and response structure. No contradictions with annotations.

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

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

The description is long but well-structured with clear sections. It front-loads the purpose and then details each mode. Every paragraph adds value, but some details like the fill check could be perhaps more concisely summarized. Given the complexity, it is appropriately 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 (multiple modes, arbitrage detection algorithm, fill check) and absence of an output schema, the description is comprehensive. It covers all modes, explains the algorithm and response structure, and even references a sibling tool for further customization. It leaves no critical gaps.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond the schema: it explains the difference between event and topic modes, provides example inputs, and details the output structure. The schema only names the parameters and gives brief descriptions; the description enriches them.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and differentiates from siblings like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning).' It explains why cross-event mode is useful. It does not explicitly state when not to use the tool or list alternatives, but the context is clear.

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

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

The description extensively discloses behavioral traits beyond annotations: caching (1h at KV level), response structure with segments and diagnostics, explanation of Fed bets exclusion, and details on how edges are computed (including pitfalls like 'Market moved X.Xpp in 24h'). Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description adds rich context without contradiction. 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?

The description is very detailed but somewhat verbose, running multiple paragraphs. It is well-structured with bold headers for segments and knobs, but the length may hinder quick parsing. Not every sentence earns its place; some details (e.g., specific alpha values for sports) are arguably excessive for a tool description. A more concise version could improve usability.

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

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

Despite no output schema, the description thoroughly explains the response structure: top-level fields (by_segment, fed_candidates, _diagnostics) and per-opportunity metrics (edge_pp_net, kelly_fraction, etc.). It covers caching, edge-knob filters, and even diagnostic counters. Given the tool's complexity (9 parameters, nested logic), the description is exceptionally complete.

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

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

Schema coverage is 100%, but the description adds significant value, explaining each parameter's purpose, default, and reasoning. For example, slippage_pp discusses Polymarket's zero fees and bid/ask spreads, and min_partition_leg_kelly explains why min_kelly doesn't apply to partitions. This goes well beyond the schema descriptions, helping an agent choose appropriate 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 the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan'), identifies the resource ('Polymarket markets'), and describes the output ('opportunities'). The phrase 'Built for "what should I bet on today"' further clarifies its use case, distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description provides clear context on when to use the tool, e.g., 'agents discover opportunities without paging hundreds of markets.' It explains the three segments and tradeable-edge knobs. However, it does not explicitly mention alternatives or when not to use it, which could be improved. The sibling list includes polymarket_arbitrage, but the description doesn't differentiate from it directly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=False. The description adds valuable behavioral details: it reads from snapshots, has a 60-day TTL, gaps in data, and decay computed from daily closes (not intraday). 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 structured with a clear purpose statement, a concrete question-answer illustration, parameter details, response format, and limitations. Every sentence adds value, though it could be slightly trimmed 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?

Despite lacking an output schema, the description thoroughly documents the response structure (tracked, expired, snapshot_dates) with field semantics. For a 2-parameter tool with no nested objects, this is sufficient for an agent to understand inputs and 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% with descriptions for both parameters. The description adds context: default and max values for days, default and possible values for window (24hr, 1wk, 1mo), and explains that window denotes the snapshot family. This goes beyond what the schema 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 states a specific verb-resource pair: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a clear question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling polymarket_edges by focusing on historical trends rather than raw snapshots.

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

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

The description clearly explains when to use this tool (to differentiate fresh vs aged edges) and includes limits and caveats (60-day TTL, gaps, decay computed from daily closes). It does not explicitly state when not to use or name alternative tools, but the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint=true, destructiveHint=false. The description adds behavioral details: walks the order book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict; for basket mode, explains theoretical vs realizable sum, capture_ratio, thin_legs, and forced_directional_risk. Discusses partial fill risks and dominance of directional loss in arb-bot P&L.

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 substantive and well-structured with separate headings for SINGLE-MARKET and BASKET modes. While every sentence adds value, it is relatively long (approx. 200 words). Could be slightly more concise, but the structure helps readability.

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

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

Given the tool's complexity (dual modes, risk assessment), no output schema, and no nested objects, the description is exceptionally complete. It covers all parameters, return values for both modes, behavioral context (when to use), edge cases (thin books, partial fills), and the forced_directional_risk legs. Leaves no gaps for the agent.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond schema: explains that market is for single-market mode, event for basket mode, and size_usd interpretation differs (max spend/target proceeds vs settlement notional). Also explains default side logic (auto from partition sum) and constraints like clamp 10–1,000,000.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth, distinguishes between single-market and basket modes, and names specific use cases (e.g., before polymarket_arbitrage signals or trades >$500). This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains risks of partial basket fills and directional exposure, providing clear context for when not to proceed without this check.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are confirmed and the description adds critical behavioral details: conditions for non-equivalent bet shapes (compatibility_warning), temporal alignment check, and leg-pair matching counters. No contradictions.

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

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

The description is well-structured with clear sections (purpose, modes, response, safety fields). It is slightly verbose but every sentence adds necessary context; 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?

Despite no output schema, the description fully explains the return format (leg-by-leg prices, top_spreads_pp, safety fields) and covers all edge cases (compatibility_warning conditions, temporal alignment, skipped counters). Comprehensive for a complex tool.

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

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

Schema coverage is 100%, and the description adds value by explaining that 'topic' auto-fetches matching events while explicit tickers override, with concrete examples. It also clarifies that most topic shortcuts yield warnings, which is not obvious from the schema alone.

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

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

The description uses a specific verb ('Cross-venue spread') and clearly identifies the resource (Kalshi and Polymarket). It distinguishes from sibling tools like 'polymarket_arbitrage' by focusing on cross-venue comparison with detailed conditions for meaningful 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?

The description explicitly states two modes (topic shortcuts vs explicit tickers) and includes safety fields (compatibility_warning, temporal_alignment) that guide when the tool should not be used for trading. It also warns that most pre-mapped topics currently return warnings, reducing false expectations.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds context about identifier-based scoping and pairing with other tools, going 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?

Three sentences with no wasted words, front-loaded with the main action, then context and pairing. Highly concise and 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?

For a simple retrieval tool with one optional parameter and no output schema, the description covers scope, usage, and integration with siblings. Complete and self-contained.

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

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

Schema coverage is 100%; description explains the effect of omitting the key (list all) and the purpose of the key, adding value beyond the schema.

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

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

Description clearly identifies the tool as retrieving a saved value or listing all keys, with specific verb and resource. It distinguishes from sibling tools '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 states when to use (looking up stored context) and when to use alternatives (pair with remember/forget). Also describes scope and listing behavior.

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

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

Annotations declare readOnlyHint, idempotentHint, and openWorldHint, so the description need not repeat safety. It adds specifics: each alert carries source, citation_uri, raw event payload; mark_read flags events as read, affecting subsequent calls; polling works fine. 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?

Four sentences, each with a clear role: purpose, return fields, filtering and mark_read, polling and alternative. No wordiness or redundancy. Front-loaded with the core action.

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 explains return fields (source, citation_uri, raw payload) and behavior (mark_read, polling). It covers filtering and limits. Lacks details on pagination beyond limit, but for a simple read list tool, mostly complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal new meaning beyond the schema, such as an example type 'sec_8k' and mentions limit default implicitly. It doesn't significantly enhance understanding 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 it 'Pull fired events from your subscription feed' and returns recent alerts with details like source, citation_uri, and raw payload. It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on fired events from the feed.

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 indicates usage for fetching recent alerts and mentions filtering by type and since, plus mark_read behavior. It also notes polling works and provides an alternative endpoint for scripts/dashboards, offering context without explicit exclusion of 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?

Discloses fan-out to multiple data sources (SEC, GDELT, GNews, USPTO), fallback logic, soft-fail for USPTO, and return structure (changes grouped by source, citations). This adds significant behavioral context beyond the readOnly, idempotent hints in annotations.

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

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

The description is a single paragraph that is informative and front-loaded with purpose and examples. Every sentence adds value, though it is somewhat dense; could be slightly more structured but remains concise for the amount of detail.

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

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

Despite no output schema, the description explains return format (changes[], total_changes, citation URIs), sources, fallback, and parameter usage. Also references sibling tool for static profile. Covers all necessary context for this complex tool.

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

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

Schema coverage is 100%, but description adds meaning: explains 'since' accepts ISO date or relative shorthand (e.g., '7d', '30d', '3m', '1y') and recommends typical values. Clarifies 'type' only supports 'company' and 'value' accepts ticker or CIK. This goes 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 it provides a change feed for a company in a time window, with specific verb 'change feed' and resource 'company'. It distinguishes from the sibling tool 'entity_profile' by explicitly suggesting when to use the alternative for a static 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?

Provides example queries and explains when to use the tool vs. entity_profile. Mentions fallback behavior (GDELT→GNews). Does not explicitly list exclusions but offers clear context for common scenarios.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description discloses that data is key-value and scoped by identifier, that authenticated users get persistent memory, and anonymous sessions retain for 24 hours. It does not mention limits on number of keys or behavior on overwrite.

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

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

The description is concise and front-loaded with the primary purpose. Every sentence adds value: purpose, when to use, storage details, pairing with other tools. No redundancy or fluff.

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

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

For a simple key-value store tool with good annotations and schema, the description covers all needed context: purpose, usage scenario, persistence, scoping, and complementary tools. No gaps given the tool's simplicity.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description adds minor context (e.g., 'scoped by your identifier', 'stored as a key-value pair') but does not significantly enhance meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies the operation (save), resource (data), and context (across conversations/sessions). It distinguishes itself from siblings by naming complementary tools (recall, forget) and explaining 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?

The description provides clear usage guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions pairing with recall and forget. However, it lacks explicit 'when not to use' or alternatives beyond the named tools.

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

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

The description adds substantial behavioral detail beyond annotations: identifiers are labeled with source, unresolved identifiers are explicitly under `unresolved` rather than omitted, and LEI/FIGI enrichment degrades gracefully (EDGAR identifiers still return if GLEIF/OpenFIGI fail). It also discloses the internal cascading of lookup endpoints. These traits are not present in the annotations, which only declare read-only/idempotent/non-destructive safety.

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

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

The description is long but information-dense. Every sentence contributes: examples, supported types, source labeling, unresolved handling, graceful degradation, and the note about replacing manual lookups. It could be slightly more scannable with bullet points, but given the two-type complexity, the paragraph format with clear breaks is acceptable.

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

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

With no output schema, the description must explain return behavior, and it does: identifiers are labeled by source, unresolved items are under `unresolved`, and enrichment degrades gracefully. It also covers input variations for both types. It doesn't provide the exact output JSON shape, but for a resolver tool, the described semantics are sufficient. Given the tool's internal complexity, this is reasonably complete.

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

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

Schema coverage is 100% (both `type` and `value` have descriptions), so baseline is 3. The description adds meaningful context: it explains the value formats for each type with examples (AAPL, CIK, ozempic), clarifies that company accepts ticker/CIK/name, and drug accepts brand/generic. This goes beyond the schema's brief field descriptions, warranting a 4.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It includes concrete query examples and explicitly distinguishes itself from siblings by noting it should be used 'FIRST whenever you have a name but need an ID,' which positions it relative to ID-consuming tools like entity_profile and compare_entities.

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 FIRST whenever you have a name but need an ID.' It also details the supported entity types (company, drug) and the appropriate input formats for each, covering both when to use and what to expect. While it doesn't name alternative tools, the 'FIRST' instruction and scope description effectively communicate the tool's role as the default resolver.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already declare safety. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density. No contradiction with annotations.

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

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

Two sentences cover action, use case, and output. No unnecessary words. Front-loaded with the main verb and resource. Highly 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?

Even without output schema, the description explains the return format (ranked list with score, confidence, signal density). It specifies entity limit (2-8) and default model. For a tool with 4 params and 1 required, this is complete and informative.

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 all params are described. The description adds semantic value: first entity is the 'subject' for narrative, rest are competitors; models default to workers-ai; _apiKey only needed for anthropic. This clarifies usage 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 compares AI visibility across multiple entities, ranks them, and surfaces the most/least recognized. It specifies it probes with ai_visibility_check and returns a ranked list with scores. This distinguishes it from siblings like ai_visibility_check (single entity) or compare_entities.

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

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

The description gives a concrete use case: 'does Claude know about us as well as our competitors?' for competitive AI-marketing audits. It implies when to use but does not explicitly state when not to use or mention alternatives like ai_visibility_check for single entities.

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 valuable context: bundlephobia first measurement can take 5-30s, and partial failures are handled with sources_failed field. No contradiction with annotations.

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

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

The description is dense but well-organized, covering purpose, usage, behavior, and examples. It could be slightly more concise (e.g., splitting ecosystem info from usage), but it's efficient and front-loads key information.

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

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

Given the tool's complexity as a composite of two services, no output schema, and 2 parameters, the description provides adequate detail on return fields, partial failures, and ecosystem scope. Minor gap: no explicit mention of output structure for alternatives.

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% (2 params fully described). The description adds value by noting that version defaults to latest, scoped packages are accepted, and it summarizes the computed fields returned. This enriches the parameter understanding.

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

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

The description clearly states the tool performs a composite 'should I add this npm package' check covering license, advisories, version history, and bundle size. It distinguishes itself from siblings by specifying npm-only and directing other ecosystems to deps.dev:version.

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

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

Explicitly states when to use: when an agent asks about package safety, popularity, or size. It also provides guidance on alternatives for non-npm packages and explains graceful degradation of 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds significant technical detail: embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), character cap (200K with truncation flag), and that passages include character offsets for verification. This fully illuminates behavior beyond the safety profile.

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

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

The description is three sentences with no wasted words. It front-loads the core purpose, then provides usage context, and concludes with technical specifics. Every sentence contributes unique value.

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

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

Given no output schema, the description explains what the tool returns (top-N passages with character offsets and similarity scores) and mentions the truncation behavior. While it does not detail the exact output structure, for a semantic search tool this is adequate. The description is well-integrated with sibling tool information, and no obvious gaps exist.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description enriches them with concrete examples (e.g., 'a SEC 10-K body' for text, 'supply-chain risk' for query) and explains the limit parameter's range and default. This adds meaningful context beyond the schema's basic type and 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 tool's action ('semantic search INSIDE a fetched record'), specifies the inputs (text and natural-language query), and distinguishes it from siblings like ask_pipeworx_grounded. The verb-resource combination is precise and easily understood.

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

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

The description explicitly advises using this tool when a record is too large for the prompt, saving context and returning only relevant passages. It also mentions pairing with ask_pipeworx_grounded for grounding. While it doesn't list explicit when-not-to-use scenarios or alternatives beyond one sibling, the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds no behavioral context beyond what is structured. It does not mention pagination, permissions, or any side effects. Minimal value added.

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?

Extremely concise but underspecified. The single sentence fails to earn its place by providing useful information. It is not appropriately sized—a useful description would require more content.

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

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

Despite having an output schema and annotations, the description offers zero context about what the tool does, when to use it, or how it differs from siblings like 'mep' or 'plenary_documents'. The tool's existence is entirely unexplained.

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

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

Schema coverage is 0%, so the description must explain the parameters. However, the description ('Session calendar.') gives no meaning to 'term' or 'year'. These could be academic terms, financial quarters, etc. The agent cannot infer what values to provide.

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 is a tautology: 'Session calendar.' restates the tool name without specifying any action (e.g., fetch, list, view) or what session calendar it refers to. It provides no discernible purpose beyond the name itself.

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

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

No guidance on when to use this tool versus siblings. No context about prerequisites, scope, or alternatives is provided. An agent has no basis for choosing 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 show readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: requires OAuth, returns a new subscription ID, details delivery channels with constraints (SMS cap, webhook auto-disable). 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 relatively long but well-structured: core purpose first, then types, then delivery. Every sentence adds useful information. Slightly verbose in places (e.g., detailed webhook HMAC explanation), but overall efficient for the high information density.

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

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

Given the tool's complexity (nested objects, multiple subscription types, delivery channels), the description is remarkably complete. It covers prerequisites, type-specific usage, delivery options with limitations, and returns the new subscription id. No output schema, but the return value is clearly stated.

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 goes far beyond by providing detailed examples for each parameter, especially the params object (type-specific filters) and delivery object (email, SMS, webhook with constraints). 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 core action: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb ('Create') and resource ('subscription'), effectively distinguishing from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides context on when to use (proactive monitoring) and requirements (Pipeworx OAuth account, not for anonymous/BYO). Lists supported subscription types with examples and delivery options. However, it does not explicitly state when NOT to use or mention alternative tools for similar tasks.

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

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

Annotations already indicate readOnlyHint, idempotentHint, non-destructive. Description adds context about return format (category-bucketed examples from live catalog) and that it provides tool+argument shapes. 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 fairly long but front-loaded with example queries and well-structured. Every sentence adds value; could be slightly trimmed but remains 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 no output schema, description fully explains what is returned (categorized examples with tool shapes). Covers when to use, parameter behavior, and result format completely.

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 'topic'. Description expands on possible values (finance, pharma, etc.) and when to omit, adding practical guidance beyond the schema.

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

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

Clearly defines what the tool does: returns category-bucketed example questions with exact tool and argument shapes. Distinct from sibling tools like ask_pipeworx by being an onboarding entry point.

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 'Use this FIRST when you do not yet know what Pipeworx can do' and explains when to call with no arguments vs. with a topic parameter. Provides actionable usage guidance.

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

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

The description adds ownership enforcement and deactivation (not deletion) behavior beyond annotations, which are crucial for safe invocation.

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

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

Two concise sentences with front-loaded action and minimal waste.

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 this simple tool, covering ownership, side effects, and relationship to historical data.

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 does not significantly augment the parameter's meaning beyond what the schema already provides.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id', distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It is clear when to use: to cancel a subscription you own. However, no explicit when-not-to-use or alternatives are mentioned.

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

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

The description goes well beyond annotations by revealing internal routing (SEC EDGAR + XBRL fast path vs grounded pipeline), the full verdict enum, citation behavior, and critical error semantics ('could_not_verify means the check did not happen... unsupported means we looked and cover no source for it'). It even warns callers not to treat could_not_verify as evidence. This is rich behavioral context that annotations alone do not 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 long but dense with useful information. The opening list of example phrasings is somewhat redundant with 'natural-language claim verification,' but the rest of the sentences each add distinct value: routing, verdicts, caller warnings. It is front-loaded with the core purpose and usage, making it easy to scan. It could be tightened but is appropriately verbose for the tool's complexity.

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

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

With no output schema, the description fully covers return values: verdicts, actual value with citation, reasoning. It also covers edge cases (could_not_verify, unsupported) and performance benefits ('Replaces 4–6 sequential calls'). For a complex verification tool, this is complete enough for an agent to select, 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?

Although schema coverage is 100%, the description adds substantial value for tolerance_pct: it explains the range (0.5–50), how it overrides claim wording, specific guidance for hallucination detection, and the default behavior (implied by wording, capped at 5). This is a meaningful enhancement beyond the schema's bare description.

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

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

The description opens with specific natural-language trigger phrases and a clear verb+resource: 'natural-language claim verification against authoritative sources.' It distinguishes itself from sibling tools by naming concrete claim types (company-financial vs other) and explicitly stating it replaces 4–6 sequential calls, which is not the case for generic ask tools.

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

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

It states 'Use whenever the agent needs to check whether something a user said is factually correct' and clarifies which pipeline handles which claim type. However, it doesn't explicitly name alternatives (e.g., 'use ask_pipeworx for non-claim questions') or provide a when-not-to-use case, so it misses the full 5-level of explicit exclusions and alternative references.

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