Uk Parliament

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

Discloses default model (free) and condition for using Anthropic (BYO key), plus return format (score, confidence, signals, raw_response). Annotations already mark as read-only/idempotent, but description adds cost and response structure details.

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

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

Three concise sentences front-loaded with purpose, followed by key usage details and return info. No redundancy; 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 4 parameters and no output schema, description fully explains input (entity, models, _apiKey, context) and output (per-model + combined view). Covers all needed context for correct agent invocation.

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

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

Schema coverage is 100%, but description adds beyond schema by explaining default model behavior, cost implications of '_apiKey', and output structure. This enriches agent understanding of parameter usage.

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

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

Description clearly states verb ('probe'), resource ('LLMs'), and specific outcome ('score visibility 0-100 per model'). It distinguishes from sibling tools like 'ask_pipeworx' and 'deep_research' by focusing on multi-model visibility scoring.

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

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

Provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and mentions default vs. paid model usage. Lacks explicit 'when not to use' but sufficiently guides selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false. The description adds valuable behavioral context: it automatically routes to the right tool, fills arguments, returns structured answers with stable citations, works on every tier, and is fast. This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with the key directive and uses bold formatting to highlight important guidance. It is relatively long but every sentence earns its place, covering scope, alternatives, and examples without fluff. The structure makes it easy to scan.

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

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

For a tool that routes to many other tools, the description is remarkably complete: it explains the primary use case, lists example queries, details when to step up to alternatives, and notes the output format (structured answer with citation URIs). No output schema exists, but the description sufficiently covers what the agent needs to know.

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

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

The schema has 100% coverage with descriptions for all six parameters (question plus five aliases). The description adds examples, but these are also present in the schema examples. It does not provide additional meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: it routes questions to one of 5,529 tools across 1,455 verified sources, fills arguments, and returns structured answers with citation URIs. This is a specific verb+resource that distinguishes it from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly says to prefer this tool over web search for a wide range of factual questions, names alternative tools for specific use cases (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-part questions), and provides concrete examples. This is exemplary 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses that this is a working experimental router, that it currently has no active candidate and thus matches ask_pipeworx exactly, and that routing improvements are enabled live when under test. This is rich behavioral context.

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

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

The description is a bit longer than necessary but front-loaded with the core purpose. Each sentence provides distinct information (beta status, identical behavior, current state, usage guidance) without redundancy. The structure is effective, though slightly verbose.

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

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

Despite having no output schema, the description explains that the response shape is identical to ask_pipeworx, covers the current experimental status, and clarifies that it's a full working router. It provides sufficient context for an agent to understand the tool's behavior and limitations.

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

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

The input schema already provides 100% coverage with descriptions for all six parameters, including aliases. The description only says 'same arguments' and doesn't add parameter-level semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router for 5,529 tools. It distinguishes itself from its sibling by explicitly stating it is the experimental edge with candidate routing improvements. The verb and resource are specific, and the scope is clear.

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

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

The description states to use it exactly like ask_pipeworx when you want the newest routing, and mentions that results are compared against the stable router. This gives clear context on when to use it and identifies the alternative (stable ask_pipeworx), though it could more explicitly say when not to use it.

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

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

Despite annotations already declaring readOnly, openWorld, idempotent, and non-destructive, the description adds critical behavioral context: it returns explicit refusals with specific reasons, extracts only from tool results, and costs an extra LLM call. This goes 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 dense but well-organized, front-loading the core purpose and then providing usage context, return format, refusal reasons, and cost considerations. Every sentence serves a purpose, though slightly long; it remains efficient.

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

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

With no output schema, the description fully specifies the return structure on success and failure, including all refusal reason enums. It also covers when to use, alternatives, and cost implications, making it highly complete for a tool of this complexity.

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

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

Schema coverage is 100% with clear descriptions of the question parameter and its aliases. The description adds no additional parameter semantics beyond confirming natural language input, which is already captured in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool is a hallucination-resistant answer mode for high-stakes reads, specifically distinguishing it from ask_pipeworx. It names the exact behavior (extracting answers using only tool results) and contrasts with the sibling tool, making its purpose unambiguous.

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

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

Explicit guidance is given: use when answers will be quoted, cited, or acted on and facts must not be invented (e.g., financial verdicts, legal claims, medical lookups). It also provides a clear alternative and cost tradeoff, stating to prefer ask_pipeworx for casual lookups.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds extensive behavioral details: resolver confidence levels, fan-out examples, news fallback mechanisms, safety short-circuiting, closed market handling, wide spread warnings, and cancellation rule parsing. 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 detailed and well-structured with labeled sections, but it is quite long. It front-loads the purpose and key information, but some examples (e.g., fan-out examples) could be shortened or moved to a separate section.

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

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

The tool has no output schema, so the description fully explains return values: result structure, resolver contract, parent event, news fields, and edge cases. It covers low-confidence matches, closed markets, wide spreads, cancellation rules, and fallback mechanisms, making it complete for a complex research tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context for the `market` parameter (slug/URL/question text) and explains the effect of `depth` and `include_raw`, but does not significantly exceed the schema's own 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' specifying the verb and resource. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as the general research tool.

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

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

Explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. While it provides clear context, it doesn't explicitly mention when NOT to use this tool versus sibling tools, which slightly lowers the score.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, which cover safety and expected behavior. The description adds context about the specific stages included, which is useful but not essential given 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 a single sentence of 12 words, front-loading the purpose with no extraneous content. Every word contributes to understanding.

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

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

For a simple read-only tool with one required parameter, rich annotations, and an output schema, the description adequately defines the scope. It could mention that bill_id is required, but that is already in the schema.

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

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

With 0% schema description coverage and no additional parameter details in the description, the agent must rely solely on parameter name 'bill_id' and the example. The description does not explain what bill_id represents or any constraints.

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

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

The description clearly states that the tool returns all stages of a bill, listing specific stages (introduction, readings, committee, royal assent). This distinguishes it from sibling tools like get_bill or search_bills.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, scenarios, or exclusions, leaving the agent to infer usage from the tool name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. However, it does not mention rate limits or potential performance characteristics, which would be useful.

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 common query patterns. Every sentence serves a purpose, with no wasted words. It efficiently conveys the tool's function, when to use it, and key behavioral details.

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

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

Given the tool has only 2 parameters, no output schema, and annotations that cover side effects, the description provides complete context. It explains input format, output behavior, data sources, and even edge cases like off-calendar fiscal years. The agent has all necessary information to invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains what each entity type returns (companies: financial metrics; drugs: adverse event counts, etc.), provides examples for the values parameter, and clarifies sorting behavior. This helps the agent correctly construct the input.

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

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

The description uses specific verbs like 'compare', 'side-by-side comparison', and 'head to head' to clearly state the tool's purpose. It explicitly distinguishes from siblings by stating 'ALWAYS PREFER over sequential single-pack lookups' and gives example queries that cover the intended use cases.

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 the tool (comparing 2-5 companies or drugs, head-to-head) and when not to (avoid sequential lookups). It also specifies the entity types and gives concrete examples, making it clear when this tool is the best choice.

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 latency expectations (15-60s, up to ~90s), account requirements (free tier vs paid plan for depth:thorough), and the behavior of returning gaps[] without inventing answers. It also describes the depth-dependent behavior (gap recovery, contradiction scan) and semantically excerpted record handling, adding context well beyond the readOnlyHint/idempotentHint annotations. 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 long but every sentence is information-dense and earns its place, covering account requirements, use cases, alternatives, depth behavior, output format, and latency. Its front-loaded structure (account requirement first, then core capability) makes it easy to scan quickly.

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

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

With no output schema, the description fully explains the return value: a findings packet with verbatim evidence, confidence, source, fetched_at, stable citations, and gaps[]. It also covers edge cases like contradictions[], semantically excerpted content, and the citation_uri resolvability, making it 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%, but the description adds crucial semantics: it details what each depth value does (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative hops) and clarifies that the question parameter is meant for broad, multi-part decomposition. This goes well beyond the schema's structural descriptions.

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

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

The description clearly states the tool performs grounded multi-source research over Pipeworx's structured data sources, explicitly distinguishing itself from open-web search and sibling tools like ask_pipeworx. It specifies the exact verb ('research'), resource ('1455 STRUCTURED data sources'), and scope ('broad/multi-part 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?

The description explicitly states when to use this tool ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'). It also notes that if the user is not signed in, ask_pipeworx should be used instead, providing clear decision criteria and named alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds significant behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes that results are 'ready to call directly, no second schema lookup needed.' This enriches the agent's understanding 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 roughly five sentences, front-loaded with the core purpose. Every sentence adds value, including the list of domains and the note about direct callability. There is no wasted text.

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

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

Despite having no output schema, the description clearly states what the tool returns (names, descriptions, schemas with examples). For a discovery tool, this is complete and informs the agent of the exact response format. No additional context is needed.

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 mentions 'top-N most relevant tools' but does not add semantic meaning beyond what the parameter descriptions already provide. It does group aliases, which is a minor improvement but not enough to raise the score.

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

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

The description starts with a clear verb and resource: 'Find tools by describing the data or task.' It then enumerates many specific domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools which are data-retrieval tools. The purpose is unambiguous 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?

The description explicitly states when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies the alternative is to directly call a known tool, providing clear 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 indicate read-only, open-world, idempotent, non-destructive. The description adds detail on data sources (SEC, XBRL, USPTO, news, GLEIF), notes USPTO sunset May 2025 with soft-fail behavior, and mentions parallel fan-out. 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 slightly verbose but front-loaded with example queries and logically structured. Each sentence contributes meaning, though it could be tightened without loss.

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 enumerates return fields (cik, company_name, filings, fundamentals, patents, news, LEI) and explains limitations (names unsupported, patent API sunset). Complete for a complex tool.

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

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

Schema coverage is 100%, but description adds value: clarifies type enum only supports 'company', specifies value format (ticker or zero-padded CIK), and explicitly states names not supported—beyond what 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 clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call' with specific examples like 'Tell me about X' and explicitly distinguishes from chaining single-pack lookups and resolves_entity for name resolution.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and notes that names are not supported, requiring resolve_entity first. Provides clear context for when to use.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description confirms delete action but adds minimal extra behavioral context beyond what annotations provide.

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

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

Two sentences that efficiently convey purpose and usage. No unnecessary words.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and pairing with siblings. Complete and sufficient.

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

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

Schema coverage is 100% and describes the 'key' parameter as 'Memory key to delete'. Description echoes this without adding new semantic information, so baseline 3 is appropriate.

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

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

The description clearly states the action (delete) and the resource (previously stored memory by key). It distinguishes itself from sibling tools like 'remember' and 'recall' by specifying the delete operation.

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 the tool: when context is stale, task is done, or to clear sensitive data. Also mentions pairing with 'remember' and 'recall', providing clear alternatives.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint=false, indicating a safe read operation. The description adds behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This provides useful details beyond annotations, though it omits potential issues like invalid URLs or network failures.

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 main action in the first sentence, followed by a brief explanation of the process and a concise list of use cases. Every sentence adds value, and there is no redundancy or wasted words.

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

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

Given the tool's simplicity (2 parameters, no nested objects, no output schema), the description covers the core functionality, output format (markdown text), and use cases. However, it does not address error handling, invalid URLs, or network failure scenarios, which would enhance completeness for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'any URL' (mapping to url parameter) and 'maximum number of link entries' (mapping to max_links), but adds little beyond the schema's own descriptions. It does not clarify parameter syntax or constraints beyond what schema already provides.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, specifying the verb ('generate'), resource ('llms.txt file'), and context ('so AI crawlers can index the site'). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning.

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 lists three concrete use cases (getting a client's site indexed, drafting for own project, auditing competitor's AI view), providing clear guidance on when to use the tool. It does not explicitly state when not to use it, but the use cases sufficiently imply appropriate scenarios.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds the specific return fields, which is helpful but not extensive. 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 sentence, front-loaded with key information, no unnecessary words.

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

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

With an output schema present, the description covers return values sufficiently. The single parameter is fully explained.

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 carries the burden. It clarifies 'numeric bill_id' and gives an example (32456), adding meaning beyond the schema's type definition.

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

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

The description specifies the action 'Fetch', the resource 'UK Parliament bill', and the identifier 'numeric bill_id'. It lists the returned fields, clearly distinguishing it from siblings like 'search_bills' and 'bill_stages'.

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 implies usage: to get full detail for a specific bill by bill_id. While it doesn't explicitly state when not to use it, the context signals and sibling names provide sufficient differentiation.

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

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

Annotations already communicate readOnly, idempotent, and non-destructive behavior. The description adds no additional behavioral traits beyond the generic 'detail'. It does not mention response behavior, errors, or side effects, so it provides minimal added 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?

Single sentence, no wasted words. Front-loads the core purpose effectively.

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 presence of an output schema and annotations, the tool's basic purpose is clear. However, for a lookup tool with optional parameters, a brief note on typical use cases would improve completeness, but it's mostly adequate.

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

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

Schema covers 100% of parameters with descriptions (id: 'Parliament member id', includes: 'Comma-sep: ...'). The description adds no further meaning beyond the schema, so it meets the baseline but does not enhance understanding.

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

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

The description 'Member detail by member id.' clearly states the tool retrieves details for a specific member using their ID. It distinguishes from search_members, which is a sibling for searching. However, it could be more specific about what 'detail' encompasses.

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 like search_members. No mention of prerequisites or when not to use. The description lacks explicit usage context.

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

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

Annotations already indicate this is a safe, read-only, idempotent operation. The description adds value by specifying return fields and default behavior (only active subscriptions), which aligns with annotations. 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 two sentences, front-loaded with the main purpose, and every sentence is informative without 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 covers purpose, return fields, and usage context. It lacks mention of pagination or limits, but given the simple nature of a list operation, it 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%, and the description does not add significant meaning beyond what the schema already provides for the single parameter. Baseline of 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'the caller's active subscriptions', and lists the return fields. It distinguishes from siblings 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?

The description explicitly states when to use the tool ('review what you're monitoring before adding more or to find an id to cancel'), but does not mention when not to use it or 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 note readOnlyHint=false and destructiveHint=false, but the description adds valuable context: rate-limiting (5/day), no impact on tool-call quota, the claim_token lifecycle, and that feedback signals go directly to the roadmap. This discloses behavior far beyond the annotations without any contradiction.

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

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

The description is lengthy but each sentence carries necessary information, from purpose to rate limits to token workflow. It is well-organized, though slightly dense; it could be tightened without losing meaning.

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 has no output schema, the description fully explains what happens on filing (returns a claim_token) and how to later check status. It covers prerequisites, workarounds, exclusions, and operational limits, making the tool self-contained and clear for an agent.

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

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

Schema coverage is 100%, so all four parameters have descriptions. The description adds value by explaining the claim_token usage in detail ('pass it back later as pipeworx_feedback({claim_token:...})') and contextualizes the type parameter categories. This goes beyond the schema's descriptions, though not for every param.

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 exactly what the tool does: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies specific feedback types (bug, feature, data_gap, praise) and clearly distinguishes itself from sibling tools by being the sole feedback mechanism. The scope restriction to Pipeworx-served tools further disambiguates from other connectors.

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

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

Explicit when-to-use guidance is provided for each feedback type (e.g., 'wrong/stale data (bug)', 'tool you wish existed (feature/data_gap)'). Crucially, it also states when NOT to use: for tools from other MCP servers, saying 'file it with that server instead.' It gives practical tips like not pasting end-user prompts and how to check a prior report via claim_token.

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 transparency about data source (CF analytics-engine), lack of PII, and caching (5min-1h). This supplements annotations well.

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

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

Description is well-structured with bullet points and front-loaded main action. Each sentence adds value, though slightly verbose in the use case enumeration. Still effective and easy to scan.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description explains what is returned (top tools, packs, volume) and data source. It is sufficiently complete for an agent to understand the tool's purpose and output.

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 describes the window parameter with enum and effect. The tool description adds brief context ('shorter windows surface what's hot right now; longer windows show steady-state demand'), but this only slightly extends the schema's own description. Baseline 3 is appropriate.

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

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

Description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window.' It specifies the verb 'returns' and the resource 'trending data on Pipeworx', distinguishing it from sibling tools like search or entity profile 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?

Lists three explicit use cases (discovering hot data sources, confirming popular tool, aligning use case). Could also mention when not to use (e.g., for historical trends beyond 30d), but the given guidance is clear and helpful.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral details: the algorithms (monotonicity violations, partition-sum checks, Jaccard similarity threshold of 0.30, placeholder filter), the response structure (opportunities[] with gap_pp, suggested_trade, etc.), and the fill check logic (theoretical vs realizable edge using book depth). 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 dense but well-structured, front-loading the purpose and then detailing each mode, filters, and fill check. Every sentence provides useful information; no wasted words. However, the length is relatively high, which slightly impacts conciseness. Still, it earns a 4 given the complexity.

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

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

Despite lacking an output schema, the description comprehensively documents return fields (opportunities[], partition_check with sum_yes_prices, gap_from_1, etc.), algorithm details, edge cases (placeholder filter, low similarity, fill check), and references to sibling tools. It covers all necessary information for the agent to understand and invoke the tool correctly.

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

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

The input schema covers both parameters with descriptions, but the description enriches them significantly: for 'event', it explains it expects a Polymarket event slug and walks child markets; for 'topic', it explains it takes a seed question and searches related events. It also documents the default behavior (no args gives trending_scan of top ~200 markets). Coverage is 100%, and description adds substantial value 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 first sentence clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It further elaborates with three distinct calling modes (no args, event, topic), each with specific use cases, distinguishing it from sibling tools 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)', and 'topic (for cross-event scanning)'. It also advises when to use the sibling tool polymarket_fill_risk for custom sizing, and explains cross-event mode catches patterns single-event misses.

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 rich context: caching for 1 hour keyed on knobs, detailed model family logic, slippage considerations, edge computation after slippage, 24h-move warnings, Fed bet exclusion, and diagnostic counters. 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 well-structured with sections, lists, and formatting. It front-loads the overall purpose and then details each model family and response structure. Every sentence adds necessary information given the tool's complexity; there is no redundancy, making it concise for the amount of detail required.

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 response structure: by_segment, fed_candidates, _diagnostics, and what each segment contains. It covers edge metrics, tradeable-edge knobs, caching behavior, and diagnostic counters. All parameter descriptions in the schema are complete. The combination fully prepares an agent to use the tool correctly.

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

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

The input schema has 100% description coverage, providing thorough explanations for each parameter. The description adds extra context for several parameters (e.g., min_liquidity, max_spread_pp, min_partition_leg_kelly) by explaining their role in filtering tradeable edges. This goes beyond schema descriptions, justifying a score above baseline.

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

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

The description clearly states the tool scans Polymarket markets for edge opportunities using Pipeworx data, specifying the verb 'scan' and resource 'Polymarket markets'. It details the three model families and output segmentation. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which reduces clarity for selection.

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

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

The description implies use for 'what should I bet on today' and mentions knobs for filtering, providing implicit usage context. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide conditions when not to use it or when to prefer a sibling tool. Guidance is present but not explicit.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable context: snapshots are written on cache-miss (gaps), decay numbers are from daily closes (not intraday), and response structure details.

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

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

Well-structured with front-loaded purpose, followed by args, response format, and limits. Every sentence is informative, though slightly dense for quick scanning.

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?

Very comprehensive: explains response fields (tracked, expired, snapshot_dates), limits (60-day TTL), and specific behaviors (decay computation, gap reasons). Handles the complexity of a time-series analysis tool well without an output schema.

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

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

Schema coverage is 100% with clear descriptions. Description adds meaning by explaining defaults, clamps, and how each parameter relates to snapshot families (e.g., 'window' is a snapshot family). Minor inconsistency between 'max 30' and schema's 'clamp 2-30' but not contradictory.

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

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

Clearly states it provides 'edge persistence and decay telemetry' and answers specific questions about edge age and shrinkage. However, it does not explicitly differentiate itself from the sibling 'polymarket_edges' tool, though it is implied as a derived analysis.

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

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

Describes the context (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades') and provides limits (60-day TTL). Lacks explicit when-not-to-use or alternative tool suggestions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it requires one of 'market' or 'event', explains the two modes (single-market and basket), lists all return fields including verdicts (clean, degraded, cannot_fill) and warnings (thin_legs, forced_directional_risk). This transparency about failure modes and edge cases goes well beyond what annotations provide.

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

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

The description is longer but well-structured: it starts with the core purpose, then explains the two modes in separate sections with bullet-point-like lists of return fields. Every sentence adds value for understanding the tool's behavior. Minor verbosity could be trimmed (e.g., 'each share pays $1' is explanatory but perhaps redundant with schema), but overall 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 no output schema, the description exhaustively lists all return fields for both modes, including edge cases (thin_legs, forced_directional_risk) and quantitative outputs (vwap_fill_price, capture_ratio, profit_usd). It also covers the dominant failure mode ('partial basket fills convert an arb into an unhedged directional position'). For a tool with two modes and significant risk implications, this is as complete as needed.

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 all 4 parameters. The description adds additional meaning: default values for side (auto in basket mode) and size_usd (1000), clarifies interpretation of size_usd in different modes (max spend on buys, target proceeds on sells, settlement notional for basket). This enriches the schema-provided information, though the schema itself is already quite descriptive.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by being a prerequisite risk check, not the trade execution itself. The verb 'check' and resource 'edge between realizable and theoretical' are specific and unambiguous.

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

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

The description explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills convert arb to directional position), giving clear context for when not to use (e.g., small trades) and the consequence of skipping it.

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

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

The description adds substantial behavioral context beyond the annotations: it details safety fields (compatibility_warning, temporal_alignment, skipped counters), explains conditions for non-equivalent bet shapes, and warns about temporal misalignment. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and structured into modes, response fields, and safety caveats. It is somewhat lengthy but each sentence adds value, so it earns a 4 for being slightly verbose.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (venue prices, matched spreads, safety fields) and covers all critical aspects like temporal alignment and skipped comparisons, making it 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?

All three parameters are covered in the description (schema coverage 100%). The description adds meaning by listing valid topic values and explaining override behavior for explicit tickers, providing context 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, using the verb 'cross-venue spread' and specifying the resource. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explicitly explains two usage modes (topic shortcuts and explicit tickers), provides examples, and warns that most pre-mapped topics return compatibility_warning. It also describes when spreads are meaningful vs. not, effectively guiding the agent.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds scoping info (by identifier) which is not in annotations. No contradictions.

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

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

Three sentences, clear and front-loaded. Could be slightly more concise, but no extraneous information.

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

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

For a simple read tool with one parameter and rich annotations, the description covers purpose, usage, scoping, and pairing with siblings. No output schema needed.

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 key parameter's behavior (omit to list all keys), adding value beyond the schema's description.

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

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

Clearly states the verb 'retrieve' and the resource 'a value previously saved via remember' or listing all keys. Distinguishes from sibling tools like 'remember' and 'forget' by referencing them.

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

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

Explicitly says 'use to look up context the agent stored earlier' and mentions pairing with 'remember' and 'forget'. Does not explicitly state 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 read-only and idempotent behavior. The description adds context about feed persistence, polling suitability, and the effect of mark_read on subsequent calls, which is not covered by annotations.

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

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

The description is four sentences, each contributing essential information: purpose, returned fields, filtering and mark_read, and alternative access. No redundant or irrelevant content.

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

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

Given 5 optional parameters, full schema coverage, and no output schema, the description covers most needs: returns fields, filtering options, polling behavior. It does not mention pagination beyond limit/mark_read, but it is sufficient for a simple retrieval tool.

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

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

Schema descriptions cover all 5 parameters (100% coverage). The description adds value by explaining mark_read behavior ('so the next call only shows newer ones') and the context of polling, which is not in the schema.

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

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

The description clearly states 'Pull fired events from your subscription feed' and specifies it returns alerts with specific fields. It differentiates from siblings by focusing on alerts retrieval; no other sibling tool has a similar 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 mentions 'Polls work fine' and gives guidance on using mark_read for pagination. It also notes an alternative HTTP endpoint, but does not explicitly state when not to use this tool versus others.

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 significant behavioral context beyond the annotations: fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, accepted date formats, and return structure (changes grouped by source, total_changes, citation URIs). There is no contradiction with annotations.

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

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

The description is relatively compact given the complexity, with front-loaded example queries. Every sentence adds useful information, though it could be slightly trimmed without losing critical details. The structure is clear and logical.

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

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

For a tool with no output schema, the description thoroughly explains the return structure (changes[], total_changes, citation URIs) and covers all key aspects: data sources, fallback behavior, date formats, and parameter nuances. It is complete enough for an agent to use effectively.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by providing concrete examples (e.g., 'use "30d" or "1m"'), clarifying that value can be ticker or CIK, and explaining the type parameter's current limitation (only 'company' supported). This goes beyond simply restating 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 starts with clear example queries and explicitly states it provides a change feed for a company within a date window, fanning out to multiple sources. It also distinguishes itself from the sibling tool entity_profile, which serves a different purpose (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?

The description includes example queries, specifies parameter usage (e.g., 'use "30d" or "1m" for typical monitoring'), and explicitly tells when to use entity_profile instead ('when you want the static profile... regardless of window'). This provides clear usage guidance and alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context: the official API source, a cap of 25 results per call, and the return fields (title, date, house, id). It does not discuss error handling or rate limits, but these are less critical given the strong annotation coverage. 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 compact and front-loaded with the core purpose. Two sentences convey the source, filters, limit, return fields, and use case, with no redundant or filler content.

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

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

With an output schema present and annotations covering safety, the description adequately covers the tool's scope: source, filtering options, result cap, and return contents. For a read-only list operation with optional parameters, this is complete enough for an agent to understand inputs and expected results.

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

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

Schema description coverage is 100%, with each parameter already documented (take, house, date_from). The description repeats that filtering by house and start date is possible and mentions the 25-per-call limit, adding minimal value beyond the schema. It doesn't elaborate on parameter format or interactions beyond the schema's examples.

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

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

The description clearly states the tool returns recent divisions (recorded votes) in the UK Parliament, sourced from the official Hansard API. It specifies the resource (divisions) and action (list recent ones), and distinguishes itself from siblings like search_hansard or bill_stages by focusing on near-term voting activity.

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: to find what the Commons or Lords have voted on recently. It implies usage for recent-vote lookups but does not explicitly mention alternatives or exclusions, such as using search_hansard for historical queries. Still, the context is enough for an agent to select it appropriately.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds scoping by identifier and persistence details (24h for anonymous), which provide useful context beyond annotations. No contradiction; behavior aligns with annotations.

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

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

The description is moderately concise, with each sentence adding important context. It is front-loaded with the core purpose. A slight trimming could improve conciseness, but overall it is well-structured.

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

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

Given the tool's simplicity (2 string parameters, no output schema), the description is fully complete. It covers usage context, persistence, and relationships with sibling tools, leaving no ambiguity about when and how to use it.

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

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

Schema coverage is 100% with descriptions for key and value. The description adds value by explaining the purpose of the key (e.g., 'subject_property') and the nature of the value ('findings, addresses, preferences, notes'). This goes beyond the schema's basic 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 saves data for reuse later, providing examples (resolved ticker, target address, user preference). It distinguishes from siblings recall and forget, and specifies the verb 'save' with a clear resource (data scoped by identifier).

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget. Also differentiates persistence behavior for authenticated vs. anonymous sessions, giving clear guidance on when the 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?

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context beyond this by explaining graceful degradation (LEI/FIGI unavailable but EDGAR still returns), cascading internal lookups, and explicit handling of unresolved identifiers. This goes beyond what annotations provide.

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

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

The description is long but well-structured, starting with user-phrase examples, then explaining purpose, supported types, and behavioral edge cases. Every sentence contributes new information, though it could be slightly tightened without losing value.

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

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

With no output schema, the description carries the full burden of explaining what the tool returns. It covers the identifiers for both entity types, source labeling, unresolved handling, graceful degradation, and the fact that it replaces multiple manual lookups. This is complete for an agent to correctly select and invoke the tool.

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

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

Since schema description coverage is 100%, the baseline is 3. The description enriches parameter semantics by explaining the meaning of the 'company' type (returns CIK, ticker, LEI, FIGI with sources, unresolved handling) and 'drug' type (RxCUI, ingredient, brand), going beyond the schema's dry format descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with a specific verb and resource. It also distinguishes itself by listing supported types (company and drug) and giving examples of queries it handles, making its purpose unambiguous.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', which gives clear when-to-use guidance. However, it does not mention when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that it calls ai_visibility_check internally and returns specific fields (score, confidence, signal density). No contradictions.

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

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

The description is two sentences, front-loaded with the main action, and contains no redundant information.

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

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

Although there is no output schema, the description specifies the return format (ranked list with score, confidence, signal density). The simple read-only nature and good annotations mean the description is sufficiently 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% with each parameter described. The description adds that the first entity is treated as the 'subject' for narrative, which is not in the schema. This adds meaningful 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 compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and returns a ranked list. It distinguishes itself from the sibling ai_visibility_check by being a batch comparison.

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

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

The description provides clear context for use (competitive AI-marketing audits) and implies that for single entities one should use ai_visibility_check. It does not explicitly state when not to use, but the use case is well-defined.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant context: composite fan-out to two sources, partial failure handling (sources_failed list), and a specific timing caveat (bundlephobia's first measurement can take 5-30s). This exceeds what annotations provide.

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

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

The description is a single dense paragraph but well-organized: starts with core purpose, expands on what it fans out, then gives usage examples and limitations. It front-loads the most important information. Slightly verbose but maintains clarity. Minor redundancy (e.g., mentioning both 'npm package' and 'NPM ecosystem').

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 enumerates the return fields (summary block with is_latest, license, etc., per-advisory detail, links, alternative versions). It covers error handling (partial failures, sources_failed) and timing behavior. For a composite tool, this is thorough and leaves no major gaps.

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

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

Schema coverage is 100% with both parameters (package, version) already documented in the schema. The description does not add new meaning beyond what the schema provides, e.g., 'Scoped packages accepted' is already in `description` of `package`. Baseline 3 applies here.

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: a composite check for evaluating an npm package before adding it to a project. It names the resources (deps.dev, bundlephobia) and distinguishes itself from any sibling tools by specifying the npm ecosystem scope. The verb 'scan' plus 'dependency' is specific and accurate.

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

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

Explicitly instructs when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides exclusion guidance: 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly'. Warns about partial failures and timing, offering clear context for invocation.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behaviors, lowering the burden on the description. The description adds useful context: it uses the official Bills API and explains the high-level behavior of returning matching bills with their progress. It does not contradict annotations and provides some extra detail beyond the schema.

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

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

The description is three sentences, each earning its place: it states the action and data source, lists filters and return fields, and summarizes the use case. It is front-loaded with the core purpose and avoids redundancy or fluff.

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

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

Given the 8 optional parameters, 100% schema coverage, an output schema, and strong annotations, the description provides sufficient context. It mentions the external API source, the type of search, available filters, and the kinds of results returned. There are no significant gaps that would prevent an agent from using the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates the filtering categories (session, stage, member, house) and mentions sorting, but these are already fully described in the schema. It does not add meaningful per-parameter semantics beyond what the schema already provides, so the score stays 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 uses a specific verb ('Search') and resource ('legislation before the UK Parliament'), clearly distinguishing it from sibling tools like get_bill or bill_stages. It also states what is returned and the use case ('Answers which Westminster bills concern a subject and how far each has progressed'), making the purpose unambiguous.

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

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

The description provides clear context that this is a search/filter tool for bills, with explicit mention of searchable fields and filters. It does not explicitly name alternative tools, but the context strongly implies when to use it (e.g., finding bills by subject) versus fetching a single bill or browsing stages. There are no exclusions or conflicting 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, and not destructive; the description adds no behavioral context beyond 'search', missing details on pagination or output.

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

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

Single sentence with no waste, front-loaded with the main action; compact but could include more value in the same space.

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 output schema and annotations present, the description is minimally adequate but doesn't explain full-text search or filtering scope; leaves some gaps for a search 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 has 100% description coverage, so baseline is 3; the description adds no parameter info, but the schema already covers all parameters adequately.

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

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

The description clearly states the tool searches debate contributions in Hansard, but does not differentiate from sibling tools like search_bills or search_members, so it lacks explicit distinction.

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; usage is implied but not clarified with context like full-text search or filtering capabilities.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) already convey safety. Description adds searchable field categories but omits that is_current defaults to true and does not detail pagination behavior (skip/take).

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

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

Single sentence efficiently conveys purpose. Could be slightly expanded to mention optionality or defaults without losing conciseness.

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?

Output schema covers return values. With 7 optional params and no required ones, description could clarify behavior when no parameters are provided (e.g., returns all?). Still fairly complete given schema richness.

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 clear parameter descriptions. The tool description merely lists field categories without adding meaning beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states a specific verb ('Search') and resource ('MPs and Lords') with filtering dimensions (name/party/location/house). It distinguishes from siblings like get_member and search_bills by resource type.

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

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

Description provides basic usage context but does not explicitly guide when to use this tool versus alternatives (e.g., get_member for a single member, search_within for other data). No when-not or alternative mentions.

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 include readOnlyHint and idempotentHint. Description adds technical details: embedding model BGE-base-en, cosine similarity, 500-char overlapping windows, 200K char limit, truncation flag, and that passages include offsets for verification.

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?

Six sentences front-loaded with purpose. Each sentence adds distinct value: usage, benefits, pairing, technical details. 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?

No output schema but description explains return: 'top-N passages with character offsets and similarity scores.' Covers expectations and parameters.

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

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

Schema coverage is 100%. Description adds context: 'max ~200K chars' for text, natural-language query examples, default and range for limit. Adds meaning 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 'Semantic search INSIDE a fetched record.' It specifies the verb (search inside) and resource (a fetched record). It distinguishes from siblings by mentioning pairing with 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?

Explicit guidance: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' Also mentions alternative approach with ask_pipeworx_grounded.

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 the tool is not read-only but not destructive, and is idempotent. The description adds significant operational details: OAuth requirement, type constraints, delivery channel behaviors (SMS cap, webhook auto-disable), and that it returns a new subscription ID. No contradictions with annotations.

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

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

The description is well-organized with clear sections for purpose, types, and delivery. It is comprehensive but not overly verbose; however, some repetition of schema information could be trimmed for conciseness.

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 (3 parameters with nested objects, no output schema), the description covers all necessary aspects: return value, required auth, type options, delivery options, limits, and failure handling. It leaves no major gaps.

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

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

Schema coverage is 100%, baseline 3, but description greatly expands with type-specific parameters, delivery channel rules, and constraints (phone verification, rate limits). This adds substantial meaning beyond the schema alone.

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

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

Description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream' and mentions it returns a subscription ID. This distinguishes it from siblings like list_subscriptions and unsubscribe by specifying the creation action.

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

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

The description provides context on when to use (requires OAuth account) and gives examples of subscription types, but does not explicitly compare with sibling tools or state when not to use it. There is implied usage but no exclusionary 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, openWorldHint, idempotentHint, destructiveHint false. The description adds behavioral context: it returns category-bucketed examples drawn from a live catalog, with no side effects. It does not repeat annotations but adds useful detail about what happens when called.

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 common user queries, then explains the return format and parameter behavior. Every sentence adds value; no fluff. It is concise given the amount of useful information conveyed.

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 (one optional param, no output schema), the description is complete: it explains purpose, usage, parameter, return type, and even provides example topics. Combined with rich annotations, it fully informs an agent how and when to use the tool.

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

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

Schema coverage is 100% (one optional parameter with description). The description adds meaning by listing example topics ('finance', 'pharma', etc.) and explaining the effect of omitting the parameter ('for a cross-category spread'), going beyond the schema's basic 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 returns category-bucketed example questions with exact tool+argument shapes, positioning it as the onboarding entry point. It distinguishes from siblings by specifying it's for learning what Pipeworx can do and how to call meta-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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools...' This provides clear when-to-use guidance and implies when not to use (i.e., after onboarding, use specific 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 significant value beyond annotations: it states ownership enforcement, that the row is deactivated not deleted, and links to 'recent_alerts'. This expands on the annotations (readOnlyHint=false, destructiveHint=false) without contradiction.

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

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

Two succinct sentences: first states the core action, second adds crucial behavioral details. No unnecessary words, perfectly front-loaded and 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?

Given the simple single-parameter tool and no output schema, the description fully covers the tool's behavior, side effects, and relationship to 'recent_alerts'. Nothing more is needed.

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

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

The only parameter 'id' is fully described in the schema (uuid returned by subscribe). The description does not add new information about the parameter, so baseline 3 is appropriate since schema coverage is 100%.

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 'Cancel a subscription by id', a specific verb and resource. It distinguishes from sibling tools like 'subscribe' (creates) and 'list_subscriptions' (lists), and adds that the row is deactivated not deleted, clarifying the exact effect.

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: ownership is enforced and historical events remain via 'recent_alerts'. It implicitly advises using this tool only for owned subscriptions, but does not explicitly exclude misuse or mention alternatives beyond 'recent_alerts'.

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 read-only, open-world, idempotent, and non-destructive. The description goes beyond this by disclosing internal routing (SEC vs grounded), the meaning of each verdict, the presence of verification_error on could_not_verify, and the explicit warning that could_not_verify is not evidence. This adds significant 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?

The description is long but every sentence contributes unique value: trigger phrases, usage directives, routing behavior, output contract, and caveats. It is front-loaded with user intent examples and uses colons/dashes to organize dense information efficiently. No filler or redundancy.

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

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

The description covers purpose, usage, behavior, output format (verdicts, actual value, citation, reasoning), and error semantics (could_not_verify with verification_error). Since there is no output schema, the description successfully carries the burden of explaining return values, making it highly complete for a tool of this complexity.

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

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

Schema coverage is 100% and includes detailed parameter descriptions, so baseline is 3. The description adds value by explaining 'exact percent-delta math' for financial claims and how tolerance grading works, which enriches the meaning of tolerance_pct and claim without repeating 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 identifies the tool as a claim verifier with specific verbs ('verify', 'fact check') and a resource ('natural-language claim verification against authoritative sources'). It distinguishes itself from siblings like ask_pipeworx by focusing on claims and offering a structured fast path for company financials, plus a grounded pipeline for other facts.

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 whenever the agent needs to check whether something a user said is factually correct') and the two paths (SEC vs grounded) based on claim type. It also gives important caller guidance on how to interpret could_not_verify vs unsupported, which is essential for safe usage.

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