Bundestag De

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

Annotations already establish it is read-only, open-world, and idempotent. The description adds valuable context: the default free model, the BYO-key payment implication for Anthropic, and the per-model response shape. This goes well beyond annotation coverage.

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

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

Three sentences, front-loaded with the core action, then configuration, return type, and use cases. Every sentence earns its place with no redundancy.

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

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

Despite lacking an output schema, the description explicitly states the per-model return shape ({score, confidence, signals, raw_response} + combined view) and covers default behavior, prerequisites, and use cases. This is complete for a 4-parameter 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%, so the baseline is 3. The description enriches parameter understanding by noting that the default model is free and that _apiKey incurs direct costs, adding meaning beyond the schema's 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 uses the specific verb 'Probe' and clearly identifies the resource (LLMs) and deliverable (visibility score 0-100). However, it does not explicitly differentiate from similar siblings like scan_competitor_ai_presence, preventing a perfect score.

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

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

It lists concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), providing clear context on when to use the tool. It does not mention exclusions or alternative tools, but these use cases are sufficient.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context: it fills arguments automatically, returns stable citation URIs, and works on every tier. It does not contradict annotations, and the extra details enhance transparency without redundancy.

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 and front-loaded with a clear directive ('PREFER OVER WEB SEARCH'), followed by function, examples, and alternatives. Every sentence adds value, though the exhaustive list of domains could be tightened for even better 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?

Despite lacking an output schema, the description specifies the return format (structured answer with stable citation URIs), provides extensive usage context, gives concrete examples, and clearly explains when to escalate to sibling tools. It is complete for a complex meta-tool with numerous data sources.

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 with aliases for the single required 'question' parameter. The description provides example queries that demonstrate usage but adds no additional parameter-level semantics beyond what the schema already conveys. 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 explicitly states the tool's function: it routes questions to one of 5,430 tools across 1,408 verified sources and returns structured answers with stable pipeworx:// citation URIs. It also distinguishes itself from siblings like ask_pipeworx_grounded (hallucination-resistant single answers) and deep_research (broad multi-part fan-out).

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

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

The description is explicit about when to use this tool vs alternatives: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with clear step-up guidance for ask_pipeworx_grounded and deep_research. It also notes that breaking news is already handled internally, preempting a common exclusion.

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

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

Beyond the read-only/idempotent annotations, the description discloses crucial behavioral variability: routing improvements are enabled live whenever tested, and the current state (no active candidate) makes it identical to ask_pipeworx. This informs the agent that results may differ over time and are compared against the stable router for merge decisions.

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 definition in the first sentence and uses the remaining sentences for context and usage. Each sentence adds value, though the final exclamation ('Falls back to nothing') is slightly redundant, making it a bit longer than strictly necessary without hampering clarity.

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

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

Given the tool is a beta variant of a known sibling, the description offers sufficient context: it explains what it is, its current state, and how to use it. The absence of an output schema is mitigated by the 'same response shape' reference to ask_pipeworx. It could have described the response shape explicitly, but the reference suffices.

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, describing 'question' and all aliases (q, text, input, query, prompt) with natural language semantics. The description adds no parameter-specific detail; it only references 'same arguments' at a high level, which does not exceed schema-based knowledge.

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

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

The description clearly states it is a 'Beta version of ask_pipeworx: identical universal router' with a specific role (routing to 5,430 tools) and a distinct experimental nature. It distinguishes itself from siblings, especially the stable ask_pipeworx, by emphasizing it is the experimental edge for testing routing improvements.

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 it exactly like ask_pipeworx when you want the newest routing.' It also clarifies when its behavior matches the stable version ('No candidate is active right now'), and asserts it is fully functional ('Falls back to nothing — this IS a full working router'), preventing misuse or underuse.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds critical behavioral context: it returns a structured object with evidence and confidence, and refuses with specific refusal_reason values when the data doesn't directly answer. It also discloses the extra LLM call cost, going well beyond what annotations convey.

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

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

The description is dense but well-organized, front-loading the core purpose, then mechanism, output format, usage cases, and cost trade-off. Every sentence adds value with no redundancy, and the structure makes it easy to parse the success and refusal paths.

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

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

Despite lacking an output schema, the description fully specifies the return shape on success and the refusal object with all possible refusal_reason enums. It also provides context on source scope and when the tool is appropriate, making it complete for an agent to decide and invoke correctly.

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

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

The schema has 100% description coverage, listing question and its aliases. The description adds no additional parameter-level meaning beyond saying it takes a question; it doesn't provide format examples or constraints beyond the schema. Baseline 3 is appropriate since the schema already documents parameters.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and explains its mechanism: it routes like ask_pipeworx, fetches data, and extracts answers only from the tool result. This distinguishes it from the sibling ask_pipeworx by emphasizing grounded extraction and explicit refusal behavior.

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

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

The description explicitly states when to use it: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. It also gives an alternative: 'prefer ask_pipeworx for casual lookups' and explains the cost trade-off of one extra LLM call.

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 and idempotent, but the description goes far beyond by disclosing short-circuit behaviors (low_confidence_match, market_closed_or_inactive), illiquidity warnings, cancellation-rule parsing, fan-out patterns, and resolution-rule risks. This is exceptionally transparent.

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

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

The description is long but well-structured with clear section headers (RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and a front-loaded purpose statement. While verbose, nearly every sentence conveys unique and useful information, so it earns its length despite being dense.

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 response structure: result.market fields, result.analysis, evidence, parent_event, news fields, status codes, and cancellation-rule risk. It covers all edge cases an agent would need to handle, making it highly 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 covers 100% of parameters, so baseline is 3. The description adds meaningful context beyond the schema, such as default values (depth 'thorough'), impact of include_raw (20KB vs 50-500KB), and fan-out examples that clarify what 'market' input can be. This adds value above schema descriptions.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and the output (evidence packet + comparison), making it distinct from sibling tools like polymarket_edges or 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?

Explicit use cases are given ('Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'), providing clear context. However, it does not explicitly name alternatives or when-not-to-use conditions, which would make it 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 mark the tool as read-only, idempotent, and open-world. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with 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 dense but every sentence earns its place. It starts with user-phrase examples, states the core purpose, gives explicit usage guidance, then details type-specific behavior and return format. No fluff or redundancy.

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

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

With no output schema, the description clearly explains return content ('paired data + pipeworx:// citation URIs per entity') and sorting behavior. Combined with the annotations (safe, idempotent) and parameter detail, it fully equips an agent to decide when and how to 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?

Although the schema covers both parameters, the description enriches their meaning. It explains what type="company" vs. type="drug" retrieves (specific financial metrics vs. FAERS/FDA/trial counts) and gives concrete examples for values (['AAPL','MSFT'], ['ozempic','mounjaro']). This goes well beyond the schema's basic descriptions.

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

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

The description opens with explicit query patterns ('Compare X and Y', 'X vs Y', 'which is bigger') and defines the tool as a 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' This clearly states the verb (compare), resource (entities), and scope (2–5 items, parallel), and differentiates it from sibling tools like entity_profile or 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 commands 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it 'Replaces 8–15 sequential lookups.' It also separates company vs. drug use cases, providing clear guidance on when to invoke this tool vs. alternatives.

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

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

Even with annotations already declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds extensive behavioral context: account requirements, paid plan for 'thorough', expected latency (15-60s, up to ~90s), the gap[] mechanism to prevent invented answers, contradictions[] scanning, hop fields, citation URIs, and semantic excerpting of large records. No contradictions with annotations.

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

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

The description is long but every sentence packs operational detail: auth, alternatives, output format, timing, limitations, and edge cases. It is not tautological or padded, though the dense paragraph could benefit from bullet points or section breaks for parseability. It earns its length given the tool's complexity.

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

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

For a complex tool with no output schema, the description fully explains return contents (evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), timing, account tiers, and when it will fail or return empty. It covers all essential context an agent needs to decide on use and interpret results, and no output schema makes this description the sole source of that information.

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

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

Schema coverage is 100% with descriptions for 'question' (natural language, broad/multi-part fine) and 'depth' (enum with per-value explanation). The description adds meaning beyond the schema by explaining depth's behavioral impact (hop counts, gap recovery, paid tier, contradiction scan) and clarifying that decomposition is the point of 'question'. This significantly enriches the schema-only info.

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

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

The description clearly states this tool performs grounded multi-source research across Pipeworx's 1408 structured data sources, decomposing questions into facets and routing to thousands of tools in parallel. It explicitly distinguishes itself from ask_pipeworx and other siblings, and contrasts with open-web search, 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 gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, while single lookups should use ask_pipeworx. It also warns against deep_research for breaking/current news and directs users to ask_pipeworx for those cases. Alternative tools are named, and prerequisites like account sign-in and plan requirements are stated.

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

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

The description reveals important behavioral details beyond annotations: it returns top-N tool names, descriptions, and full input schemas with curated examples, and that results are ready to call directly without a second schema lookup. This adds meaningful context on top of the readOnlyHint and idempotentHint annotations.

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

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

Three concise sentences: first states purpose, second describes return value and behavior, third gives usage guidance. The domain list is useful and dense, and every word earns its place.

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

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

Given the simple schema (one meaningful parameter plus aliases and limit) and no output schema, the description fully explains what the tool does and what it returns. No significant gaps are present.

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

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

Schema description coverage is 100%, with all parameters documented including aliases for query. The description adds only that it returns top-N tools, which loosely ties to the limit parameter but doesn't add new meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task' and lists many domains. It distinguishes itself from sibling search tools that target specific data sources.

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

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

Explicitly provides when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly indicates it's a discovery tool for exploring options before selecting a specific tool.

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

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

Despite annotations already indicating read-only, idempotent, and open-world behavior, the description adds rich behavioral context: it fans out across multiple sources in parallel, returns specific fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), and discloses the patent API sunset. 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 densely packed with necessary context: example queries, use preferences, output breakdown, and caveats. Every sentence adds value, though a bit of structuring (e.g., bullet points) could improve scannability. Still, no wasted words.

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

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

For a complex tool with no output schema, the description comprehensively enumerates the return payload (categories and specific fields), clarifies input constraints, and notes fallbacks and limitations. This fully equips an agent to invoke it correctly and interpret results.

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

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

Schema descriptions cover both parameters at 100%, with clear examples for type and value. The description reinforces the value format (ticker or zero-padded CIK) and warns against names, adding slightly beyond the schema's literal wording. A strong baseline with helpful amplification.

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: 'full cross-source profile of a US public company' via a single parallel call, listing specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and outputs. It explicitly distinguishes itself from siblings by instructing to 'ALWAYS PREFER over chaining single-pack lookups' and referencing resolve_entity for name-only inputs.

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

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

Provides explicit when-to-use guidance ('when the user asks for a holistic view'), states exclusions ('names not supported — use resolve_entity first'), and mentions fallback behavior (patent soft-fail, GDELT→GNews fallback). This is strong differentiation and actionable 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 destructiveHint=true and idempotentHint=true, which cover the primary safety implications of deletion. The description adds usage context but does not disclose behavioral traits beyond what annotations provide, such as effect on non-existent keys or return behavior, though it is consistent with the annotated destructive nature.

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 action, then provides usage guidance and sibling context. Every sentence earns its place with zero 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?

For a simple one-parameter destructive tool, the description sufficiently covers what it does, when to use it, and its relationship to the memory tool family. The annotations handle safety and idempotency, while the missing output schema is not a gap for a deletion operation.

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

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

The schema description covers 100% of the parameter, defining 'key' as 'Memory key to delete'. The description's mention of 'by key' adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description starts with a specific verb ('Delete'), names the resource ('previously stored memory'), and specifies the method ('by key'). It also distinguishes itself from the sibling tools 'remember' and 'recall' by stating it pairs with them, clarifying its role as the deletion counterpart.

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

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

The description provides explicit conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also directly references the complementary tools 'remember' and 'recall', implying when to use those instead.

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

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

Annotations already cover readOnly/idempotent/destructive. The description adds that it fetches the page, extracts title/description/key links, and outputs a text blob. It does not contradict annotations. It lacks failure mode disclosure but given annotations, this is sufficient.

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

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

Three sentences, front-loaded with the core purpose, followed by process and use cases. Each sentence adds value with no filler.

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

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

The tool is simple (2 params, no output schema). The description explains what it does, how it works, what output to expect, and when to use it. This is complete for the tool's scope.

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

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

Schema coverage is 100%, with detailed descriptions for url and max_links. The description itself does not add parameter-specific information beyond the schema, so baseline 3 is appropriate.

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

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

The description names the specific deliverable (llms.txt), the verb 'Generate', and the process (fetches, extracts, emits). It distinguishes itself from sibling tools like ai_visibility_check by focusing on producing the file rather than just assessing visibility.

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

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

The description provides three concrete use cases (client indexing, own project, auditing competitor) and explains the context for using the tool. However, it does not explicitly name alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no further behavioral context beyond identifying it as a detail lookup. No contradictions are present.

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, front-loaded sentence: 'Drucksache (printed document) detail by id.' It contains no redundant words and communicates the core purpose efficiently.

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

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

Given the tool's simplicity (one parameter, no nested objects), the presence of annotations, and an output schema, the description is sufficiently complete. The 'by id' qualifier plus the schema and annotations provide enough context for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with the 'id' parameter clearly described as 'Drucksache id (numeric, as string)' and examples provided. The description itself adds no additional parameter semantics, but the schema already fully documents the parameter, so the baseline score 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 returns 'detail by id' for a Drucksache (printed document), using a specific verb+resource pattern. This distinguishes it from the sibling 'search_drucksachen' tool, which would be used for searching rather than direct retrieval.

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 the tool is appropriate when an id is known ('by id'), suggesting it should be used for direct lookup rather than searching. However, it does not explicitly mention alternatives like 'search_drucksachen' for cases where the id is unknown, leaving the usage guidance implicit.

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?

With annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description's main added value is stating the return shape: 'returns date, session number, and associated agenda items and speakers.' This goes beyond the annotations and helps set expectations, though it does not detail edge cases or error behavior.

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

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

The description is a single, well-structured sentence that front-loads the action and key resource, then lists return contents. No wasted words; every clause earns its place.

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

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

For a one-parameter fetch-by-ID tool with rich annotations and an output schema, the description is fully adequate. It states the resource, ID-based lookup, and key return fields; there is no missing information that the agent needs to select or 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 for the single parameter is 100%, so the description carries little burden. It adds 'numeric id string' which is slightly misleading given examples like '20/234' include a slash, but the schema examples already convey the expected format. Baseline score of 3 is appropriate.

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

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

The description opens with 'Fetch full detail for a single Bundestag plenary protocol (Plenarprotokoll) by its numeric id string', which clearly states the verb, resource, and scope. It explicitly mentions the return content (date, session number, agenda items, speakers), and distinguishes itself from sibling search/get tools like get_drucksache and search_plenarprotokolle.

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 makes it clear this is for fetching a single protocol by ID, implying it should be used after identifying an ID rather than for discovery. It does not explicitly name 'search_plenarprotokolle' as the alternative for finding protocols, so it stops short of a full when/when-not statement.

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, so no safety concerns remain. Description adds 'caller's' scope and returned fields, which is useful context, but no additional behavioral traits like rate limits or auth requirements are disclosed.

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

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

Two sentences, front-loaded with the action. Each sentence earns its place: purpose, return fields, and usage context. 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 tool is simple, has no output schema, and the description covers purpose, return fields, and practical usage. The sibling context (subscribe/unsubscribe) makes its role clear, and the description is sufficient for an agent to select and invoke 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 has 100% coverage for the single parameter include_inactive with a clear description. The tool description adds no parameter-specific detail, so baseline 3 is appropriate.

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

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

Description uses specific verb 'List', names resource 'subscriptions', and clarifies scope 'caller's active subscriptions'. It also lists returned fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly states two use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. This provides clear context for when to invoke, though it does not name alternative tools or give exclusions.

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

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

Annotations provide no hints (all false), so the description carries the burden. It discloses rate limiting (5 per identifier per day), that it's free and doesn't count against quota, and that the team reads digests daily. It adds valuable behavioral context beyond the schema without contradicting annotations.

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

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

The description is a single front-loaded paragraph. Every sentence earns its place: purpose, when, when-not, content guidance, rate limit, quota. It is sufficiently detailed without being verbose, matching the tool's complexity.

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

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

Given 3 parameters, no output schema, and empty annotation hints, the description covers all essential context: purpose, scope, exclusions, content constraints, and operational limits. This is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by clarifying how to phrase feedback (describe in terms of Pipeworx tools/packs, don't paste the user's prompt) and by mapping the 'type' enum to real-world scenarios. This enrichment pushes it 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 states exactly what the tool does: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates use cases (bug, feature, data_gap, praise) and clearly differentiates from siblings by being the only feedback tool among many research/search 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 tells when to use it: for tools served by this Pipeworx connection, and when not: if the tool came from a different MCP server. It also tells the agent how to disambiguate ('Pipeworx tool names are the ones this connection lists') and what to include in the feedback.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond the annotations: data source (CF analytics-engine), privacy (no PII), output granularity ((pack, tool, count)), and caching (5min-1h). This exceeds what annotations alone provide.

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

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

The description is compact but packs in purpose, outputs, use cases, provenance, privacy, and caching. It is structured with numbered use cases and a final sentence for data characteristics. While not as terse as a single-sentence description, every line earns its place without fluff.

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

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

With no output schema, the description sufficiently describes the return contents (tools, packs, volume) and the nature of the data (aggregated, no PII). It also covers caching and window implications. It could be slightly more explicit about exact response format, but for a read-only analytics tool with one optional parameter, this is comprehensive.

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

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

Schema coverage is 100% and the schema parameter description already explains the window option semantics (shorter vs longer windows). The tool description only repeats '24h, 7d, or 30d' without adding additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb-resource pairing ('What other AI agents are calling on Pipeworx right now') and enumerates exact outputs: top tools, top packs, and total call volume. This clearly distinguishes it from sibling tools like search_within or discover_tools by focusing on aggregate trending usage rather than individual queries.

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

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

The description provides three concrete use cases (discovering hot data sources, confirming canonical tool choice, aligning usage with agent needs). While it does not explicitly name alternatives or say when not to use it, the use cases give strong context for appropriate 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the partition filter dropping placeholder slugs, the fill check pricing against live CLOB depth, and the warning that realizable_edge_pp <= 0 means the overround is not in the book. It also defines the semantic anchor requiring >=0.30 Jaccard similarity, preventing spurious cross-event pairs.

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 each section (trending_scan, event, topic, semantic anchor, partition filter, fill check) adds necessary operational detail. The use of uppercase labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) provides structure, though it could benefit from bullet points for even better readability.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly covers return values (opportunities[] with fields, partition_check object) and edge cases (fill check, placeholders). It also addresses the no-arg mode and provides gotchas like the realizable_edge_pp condition.

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 only gives type and basic examples, but the description explains the behavior for no-arg calls (trending_scan) and elaborates on each parameter's mode with examples and expected results. It also clarifies that event slugs and full URLs are accepted, and topic searches related events across the platform.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, with specific modes (event, topic) and a no-args trending scan. This distinct verb+resource+method distinguishes 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?

It explicitly recommends `event` for a specific market and `topic` for cross-event scanning, and notes cross-event catches patterns single-event misses. It also directs users to `polymarket_fill_risk` for custom sizing, providing clear when-to-use vs alternatives.

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

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

The description is exceptionally transparent about behavior: it details the three response segments, model families, edge computation with slippage, Kelly sizing, liquidity/spread filters, diagnostics for empty segments, the Fed note, and the 1-hour cache. This far exceeds what the annotations (readOnlyHint, idempotentHint) already convey, adding critical context about output semantics and filtering logic.

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

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

The description is very long and dense, but every sentence carries substantive detail about model families, response structure, edge computation, and knobs. It is front-loaded with the core purpose and then dives into specifics, but the paragraph style with all-cap section labels could be more readable with lists or clearer separation. Still, it is well-structured 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?

With no output schema, the description fully compensates by enumerating the top-level response (by_segment, fed_candidates, _diagnostics), explaining what each segment contains, warning about 24h moves, and telling callers how to interpret empty segments. It also covers caching behavior. This is a highly complete description 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?

Even though schema description coverage is 100%, the narrative adds substantial meaning beyond the schema. It explains how min_edge_pp is evaluated net of slippage, how min_partition_leg_kelly applies per-leg for partition arbs (which always have parent-level kelly_fraction_half=0), and how min_liquidity/max_spread_pp act as tradeability gates. These interactions are not evident from the schema alone.

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

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

The description clearly identifies the tool's purpose: scanning Polymarket markets to surface opportunities where Pipeworx data disagrees with market price. It goes into specific model families and response segments, making the core function unambiguous. However, it does not explicitly differentiate itself from sibling tools such as polymarket_arbitrage or polymarket_edge_tracker, so it misses the top score for sibling 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?

The description states a clear use case: "what should I bet on today" and that it saves agents from paging hundreds of markets. It also explains how knobs like min_liquidity and max_spread_pp filter out unrealizable edges. However, it does not explicitly say when to use this tool instead of a sibling like polymarket_arbitrage, nor does it give any 'when not to use' guidance.

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

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

The description goes far beyond the annotations by disclosing multiple behavioral traits: snapshots are written only on cache-miss (so gaps mean no scan), history depth is bounded by a 60-day TTL, decay numbers come from daily closes (not intraday), and edge values are signed with negative meaning SELL YES. These details are not present in the annotations, which only cover read-only/idempotent/destructive hints.

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

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

The description is long but exceptionally well-structured into three labeled sections (purpose, args, response, limits). Every sentence delivers distinct, non-redundant information. The response format is described with precise field names and meanings, making it easy for an agent to parse. No word is wasted.

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

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

There is no output schema, so the description fully explains the response structure: tracked[], expired[], and snapshot_dates[] with their meanings. It also covers critical limitations (TTL, snapshot gaps, daily close basis) and the implications of the data. Combined with the detailed annotations and sibling tool context, this is completely adequate for an agent to select and invoke the tool correctly.

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

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

The schema already covers 100% of the parameters with descriptions, including defaults and clamps. The description's 'Args: days (lookback, default 14, max 30), window (snapshot family, default "1wk")' essentially restates the schema. While it clarifies the terminology 'snapshot family', it does not add meaningful new semantics beyond the schema, 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 opens with a specific verb phrase 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and immediately states the core question it answers: 'how long has this edge existed and is it shrinking?'. This clearly distinguishes it from sibling tools like polymarket_edges (which likely only shows current edges) by focusing on historical persistence and decay.

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

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

The description provides a clear context for when to use this tool: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take)'. This implies usage for evaluating edge age/shrinkage, but it does not explicitly name alternative tools or state 'when not to use'. It lacks explicit exclusions, so it earns a 4 rather than 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 mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: it walks the order-book ladder, distinguishes between top-of-book and VWAP fills, handles both single-market and basket modes, and returns a verdict (clean|degraded|cannot_fill) plus risk metrics like forced_directional_risk. There is no contradiction with annotations; the description enriches them with operational 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?

Although the description is long, it is densely informative and well-structured, with explicit labels for SINGLE-MARKET and BASKET modes. Every sentence contributes to understanding the tool's behavior, return values, or usage context. The main purpose is front-loaded, and no waste or redundancy is present.

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 and only basic safety annotations, the description carries the full burden of explaining outputs and edge cases. It lists all major return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, capture_ratio, thin_legs[], forced_directional_risk, etc.), explains size_usd semantics for both modes, and articulates the risk rationale. This is a complete, self-sufficient description 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%, with each of the four parameters already described in detail (side options, market/event selection, size_usd interpretation and clamping). The description adds some interpretive phrasing ('max spend on buys, target proceeds on sells') but does not materially extend beyond the schema. Baseline 3 is appropriate when schema carries the load.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings by focusing on fill risk and explicitly referencing related tools (polymarket_arbitrage, polymarket_edges) in the usage guidance. The two modes (single-market vs basket) are explained in detail, leaving no ambiguity about what the tool does.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, citing the risk of theoretical overround on thin books and partial basket fills converting arbitrage into unhedged directional positions. This is exemplary when-to-use guidance with named alternatives and clear conditions.

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

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

The description goes well beyond the read-only annotations by disclosing the two compatibility warning conditions, the temporal alignment fields, and the skipped_cross_type/subtype counters. It also clarifies the output structure ('leg-by-leg prices ... plus matched spread[].top_spreads_pp') and the caveat that spreads are invalid when aligned:false. No contradiction with annotations exists.

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

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

The description is long and dense, but it is organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and avoids fluff. Some redundancy exists (e.g., repeating the equivalence caveat), but the structure helps an agent parse the complexity. It earns a strong score, though not a perfect one due to its length.

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

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

Given the tool's complexity (3 optional params, dual modes, no output schema), the description is remarkably complete. It covers the response format, safety fields (compatibility_warning, temporal_alignment, skipped counters), and edge cases, including when spreads are mathematically meaningless. No output schema exists, so the description fully compensates by explaining return values.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful context by explaining how the two modes interact ('topic ... auto-fetch the matching event' vs 'explicit kalshi_event_ticker + polymarket_event_slug for custom pairings') and that explicit parameters override the topic-mapped side, which enhances semantic understanding beyond the schema notes.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly identifies the tool's specific verb, resource, and scope. It distinguishes this tool from sibling Polymarket tools like polymarket_arbitrage and polymarket_edges, which focus on other spread/edge concepts. The purpose is explicit 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 outlines two explicit modes — topic shortcuts and custom pairings — and explains when each is appropriate. It also warns that 'most pre-mapped topics return compatibility_warning today' and that 'pre-mapped ≠ tradeable,' providing clear context for when the tool may not be useful. However, it does not name alternative tools directly, so it stops short of full when-not-to-use guidance.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context about scoping (anonymous IP, BYO key hash, or account ID), which is useful for the agent to understand data isolation. No contradictions with annotations.

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

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

Two concise sentences that front-load the verb and resource. Every sentence earns its place, including usage guidance and scoping. No redundancy or fluff.

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

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

For a simple tool with one optional param and no output schema, the description covers both modes of operation (retrieve and list) and mentions scoping. It could explicitly state the return format (e.g., 'returns the stored value or a list of keys'), but the current wording is sufficient for an agent to infer behavior.

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

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

Schema coverage is 100% with a clear description of the key parameter. The description enriches this by providing examples of key values (ticker, address, notes) and explicitly stating the omit-to-list-all behavior, adding practical semantics beyond the schema.

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

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

The description clearly states the tool's function: retrieve a value saved via remember, or list all saved keys if key is omitted. It provides concrete examples (target ticker, address, research notes) and distinguishes itself from sibling tools like remember and forget.

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

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

The description gives explicit context for when to use this tool ('look up context the agent stored earlier') and names related tools (remember to save, forget to delete). It lacks an explicit 'when not to use' clause, but the use case is clear given the tool's specific purpose.

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 documents a state-changing behavior via the mark_read parameter ('flag returned events read'), which directly contradicts the readOnlyHint annotation that indicates no side effects. This is an annotation contradiction.

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

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

Four sentences, front-loaded with the main purpose and return contents. Each sentence provides distinct value, including the external URL alternative, with no redundancy or fluff.

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

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

Without an output schema, the description adequately describes the returned fields (source, citation_uri, raw payload) and covers filtering, mark_read, and polling behavior. The annotation contradiction reduces overall trust but does not leave major informational gaps for a read-heavy tool.

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

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

Schema coverage is 100%, but the description adds meaningful extra context: it gives an example filter value ('sec_8k'), clarifies since as an ISO timestamp, and explains the consequence of mark_read (next call only shows newer events). This goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the user's subscription feed and returns the most recent alerts written by the evaluator. This specific verb+resource combination distinguishes it from siblings like recent_changes or list_subscriptions.

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

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

It indicates polling is acceptable and notes an external URL for scripts/dashboards, effectively suggesting when to use the HTTP endpoint instead. Though it doesn't explicitly name alternative tools, it provides clear usage context.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive; the description goes further by disclosing the parallel fan-out to three sources, the GDELT→GNews fallback on rate-limit/5xx, and the USPTO soft-fail pending reactivation. It also states the return shape (changes[] grouped by source + total_changes + citation URIs), adding substantial behavioral context beyond the annotations.

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

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

The description is long but dense and information-rich, front-loaded with usage examples and ending with the key alternative. Every sentence carries functional value: sources, fallback, date formats, return structure, and differentiation from entity_profile. No filler or repetition beyond the illustrative query patterns.

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 three params and no output schema, the description compensates fully: it explains the return structure (grouped changes, total count, citation URIs), the data sources and fallback behavior, the accepted `since` formats, and the relevant sibling tool. This is a complete picture for an agent to select and invoke the tool correctly.

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

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

Schema already covers all three parameters at 100%, so baseline is 3. The description enhances `since` by giving concrete relative-shorthand examples ('7d','30d','3m','1y') and recommending '30d' or '1m' for monitoring, which goes beyond the schema's generic 'ISO date or relative' wording.

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

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

Description opens with natural-language triggers and defines the tool as a change feed for a company over a window via SEC EDGAR, GDELT/GNews, and USPTO. It clearly identifies the verb ('change feed') and resource (company), and closes by distinguishing from entity_profile.

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

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

Provides explicit usage triggers ('What's new with X', 'latest on Y') and an explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This tells the agent both when to use and when not to use the tool.

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

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

Adds valuable behavior beyond annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours, and data is stored as key-value pairs. This contextualizes the idempotentHint and destructiveHint without contradiction.

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

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

The description is compact and front-loaded: first sentence states the purpose, second gives usage scenarios, and remaining sentences clarify scoping, persistence, and companion tools. 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?

For a simple two-parameter key-value write tool, the description covers the full lifecycle: what, when, how (key-value), persistence behavior, and integration with recall/forget. It is self-sufficient without needing 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 descriptive examples for both parameters (key and value). The description adds examples of use cases but does not extend the parameter semantics meaningfully beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb ('Save data') and resource ('data the agent will need to reuse later'), and distinguishes itself from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete.' This makes its specific role in the memory system unambiguous.

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

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

Provides explicit guidance: 'Use when you discover something worth carrying forward' with concrete examples, and names companion tools (recall, forget) for related operations. This tells the agent exactly when to use it and what the alternatives are.

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 beyond these: it explains internal cascading ('Each call cascades through several lookup endpoints internally'), return details (citation URIs, auto-disambiguation), and output structures for each type. 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 user queries and a clear one-liner of the tool's purpose. It then efficiently lists supported types with example inputs and outputs. Every sentence contributes useful information—no fluff or repetition of the schema. Despite length, it's tightly packed and well-organized.

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

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

The tool has simple parameters and no output schema, but the description thoroughly explains return values and use cases. It covers both supported types, input formats, and even internal behavior. Minor gaps remain (e.g., failure/not-found behavior), but overall it is complete enough for an agent to confidently invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches semantics by explaining that 'value' accepts multiple formats (ticker, CIK, name for company; brand or generic for drug) and that results are auto-disambiguated. It also clarifies what each type returns, which is not in the schema, thus adding meaningful meaning to both parameters.

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

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

The description clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides specific verbs and resources (company: ticker/CIK; drug: RxCUI) and differentiates from siblings like entity_profile by focusing on name-to-ID resolution. Examples of user queries make the purpose immediately understandable.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported types and input formats, which helps the agent decide when to invoke. However, it stops short of naming alternatives or explicit when-not scenarios, such as 'if you already have the ID, use entity_profile instead.'

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

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

The description adds meaningful behavioral context beyond the readOnly/idempotent annotations: it ranks by score, surfaces most/least recognized, and specifies the returned fields (score, confidence, signal density). Annotations already cover the safety profile, so this extra context elevates the score.

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 focused sentences, front-loaded with the core purpose, followed by mechanism and use case. Every sentence earns its place with no redundancy or filler.

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

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

With no output schema, the description compensates by defining the ranked output (score, confidence, signal density per entity). Combined with fully documented schema and annotations, it provides sufficient context for correct invocation and result interpretation.

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% (all 4 parameters documented), so the baseline is 3. The description clarifies that entities represent 'your brand + N competitors' but doesn't add substantive parameter semantics beyond what the schema already provides.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It further specifies the mechanism (probes each entity with ai_visibility_check) and the output (ranked list), distinguishing it from the sibling single-entity tool ai_visibility_check.

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 a concrete use case ('competitive AI-marketing audits') and implies when to use this over a single-entity check. However, it doesn't explicitly state when not to use it or name alternative tools beyond the implicit reference to ai_visibility_check.

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

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

Goes beyond the readOnlyHint/openWorldHint/idempotentHint annotations by disclosing behavior: it fans out to two services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and failures are reported in sources_failed. 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 somewhat long but every sentence earns its place: purpose, use cases, return data, ecosystem limitation, and failure behavior. It is front-loaded with the core purpose. Slightly dense but appropriate for the tool's composite 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?

For a tool with no output schema, the description lists all key return fields, notes partial failure behavior, explains the 5-30s first-measurement delay, and scopes the ecosystem. This is comprehensive given the tool's complexity and lack of structured 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 descriptions for both package and version. The description adds the NPM-ecosystem constraint and mentions the version default, but these are already implied by the schema. It does not substantially extend parameter meaning beyond the schema.

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

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

The description opens with a specific verb+resource: a composite 'should I add this npm package to my project' check, fanning out to deps.dev and bundlephobia. It clearly distinguishes from siblings by scoping to NPM and naming the direct alternative for other ecosystems.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also gives a clear exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context about the controlled DIP vocabulary, explaining that queries match a controlled German vocabulary rather than free text, which is not captured 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 three concise sentences: the first states scope and filters, the second explains the controlled vocabulary behavior, and the third points to an alternative. Every sentence earns its place with no redundant content.

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

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

For a read-only filtered search tool, the description covers the core functionality, filter options, matching behavior, and an alternative tool. With an output schema present and comprehensive annotations, the remaining details (e.g., pagination cursor, output format) are adequately captured by structured data.

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

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

Schema description coverage is 100%, with all 8 parameters described in the schema. The description reinforces the GND descriptor constraint but does not add new parameter-specific details beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as searching Bundestag/Bundesrat parliamentary activities, filtered by GND subject descriptor with optional ministry/date. It distinguishes from the sibling search_drucksachen by noting that tool handles full document search.

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

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

It provides explicit when-to-use guidance: 'parliamentary activities filtered by GND subject descriptor' and instructs to 'pass a precise German subject term.' It also gives a clear when-not/alternative: 'For full document search use search_drucksachen instead.'

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

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

Annotations already mark the tool as read-only and non-destructive, so the description doesn't need to restate safety. However, it adds no behavioral context such as pagination behavior, result filtering, or query syntax limits. The description neither contradicts nor enriches 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 that states the purpose clearly without filler words. It is front-loaded and every word contributes to the 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?

For a 6-parameter search tool with cursor pagination, the description is minimal. The output schema and annotations partially compensate, and the core purpose is clear. However, it lacks details on query construction, date filtering, and pagination, making it only minimally sufficient for an agent to use confidently.

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 only 17% (only drucksachentyp has a description). The description fails to explain the meaning or format of num, query, cursor, date_from, and date_to. The parenthetical 'bills, motions, answers' loosely maps to drucksachentyp but adds no information 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 uses the specific verb 'search' and identifies the resource as 'printed documents,' clarifying the domain with examples ('bills, motions, answers'). This clearly distinguishes it from sibling tools like get_drucksache (retrieve a single document) and search_plenarprotokolle (search parliamentary protocols).

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 that it covers all types of printed documents or how it differs from searching plenary protocols. Usage context is only implied, not stated.

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

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

Annotations already cover safety (readOnly, openWorld, idempotent, non-destructive), so the description adds value by disclosing pagination via cursor and the limitation that no name-based filtering exists. It does not contradict annotations and enriches the behavioral context.

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

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

Two concise sentences with a clear lead statement and a critical note. Every sentence adds essential information without wasteful repetition.

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

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

Given the simple optional-parameter schema and existing output schema, the description is complete. It states the tool's scope, pagination behavior, and the key limitation, leaving no critical gaps for an agent to misuse 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 description coverage is 100%, with both num and cursor already described. The description adds only a minor mention of cursor pagination, which the schema already conveys, so it contributes no significant meaning beyond structured fields.

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 the specific verb 'List' with a clear resource ('people referenced in DIP') and scope ('members, ministers, witnesses'). It explicitly distinguishes itself from name-search lookups by noting DIP has no name search, differentiating it from sibling tools like search_drucksachen.

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

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

It states exactly when not to use this tool ('you cannot filter /person by name') and provides an explicit alternative ('locate them via search_drucksachen'). This gives the agent clear guidance for choosing the right tool.

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

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

Annotations already convey read-only and non-destructive behavior, so the bar is lower. The description adds valuable behavioral context: the non-searchable nature and the fact that protocol titles are only session numbers. 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 two sentences, front-loaded with the core purpose, and contains zero fluff. Every sentence earns its place by either describing the function or providing necessary routing guidance.

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

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

The tool is a simple list operation with a clear output schema and annotations covering safety. The description adequately conveys its scope, limitations, and how it fits with sibling tools. Missing details about pagination or num/cursor are minor given the presence of an output schema and examples.

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

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

Schema description coverage is 0%, so the description must compensate. It only mentions 'by date range', which partially explains date_from/date_to, but does not explain num or cursor. Given the schema itself provides no descriptions, leaving two parameters unexplained is a significant gap.

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: 'List Bundestag plenary protocols (transcripts) by date range.' It uses a specific verb and resource, and distinguishes itself from sibling tools by explicitly noting it is NOT keyword-searchable, while pointing to alternatives like search_drucksachen.

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

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

It provides explicit guidance on when to use this tool versus alternatives: 'for a topic use search_drucksachen; open a specific protocol with get_plenarprotokoll.' It also states a clear exclusion ('NOT keyword-searchable'), making the usage context unambiguous.

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

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

Annotations already mark the tool read-only, open-world, idempotent, and non-destructive; the description adds meaningful behavioral detail beyond these hints. It discloses the return format (top-N passages with character offsets and similarity scores), the embedding model (BGE-base-en), the chunking strategy (500-char overlapping windows), and the 200K character cap with truncation flagging. No contradiction with annotations is present.

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 in the first sentence, and every subsequent sentence adds either behavioral detail, usage guidance, or pairing information. While moderately lengthy, there is no fluff—statements like 'every passage carries an offset so the agent can verify a verbatim quote' justify the design.

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

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

With no output schema, the description compensates by specifying what the tool returns (passages, offsets, similarity scores). It also covers input constraints (200K cap, truncation) and the workflow pairing with ask_pipeworx_grounded, making the tool fully self-contained for an agent.

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

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

The input schema already covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra context by clarifying that 'text' should be fetched content, that 'limit' produces top-N passages, and by giving concrete query examples. This pushes parameter semantics above 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 opens with 'Semantic search INSIDE a fetched record', clearly stating the specific action and resource. It distinguishes search_within from fetch-oriented siblings by emphasizing the text is already pulled, and it names a complementary tool (ask_pipeworx_grounded). This makes the tool's purpose unambiguous.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt', providing a concrete when-to-use signal. It also contrasts with ask_pipeworx_grounded by noting the pairing pattern: fetch with the gateway, then ground over passages. This gives the agent actionable guidance on alternative workflows.

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

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

Beyond the annotations (readOnlyHint: false, idempotentHint: true, etc.), the description adds concrete behavioral context: auth requirement, phone verification for SMS, a 10/day cap, always-on feed, and the return of a subscription ID. It also implies side effects (creating a persistent subscription), consistent with the non-read-only annotation. 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 a long, dense paragraph that packs many type examples and channel details. It front-loads the core action but quickly becomes crowded with embedded examples and caveats. It could benefit from bullet points or more structured formatting, though every sentence contributes necessary information for the tool's complexity.

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

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

Given the absence of an output schema, the description covers the return value (subscription ID) and comprehensively explains subscription types and delivery channels. It omits webhook details at the top level, but those are fully detailed in the schema's delivery description. The description is sufficiently complete for the tool's complexity, though it could briefly mention that its full parameter semantics live 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?

While the schema already provides 100% parameter descriptions, the description adds semantic examples that clarify meaning beyond enumeration: sec_8k items:['5.02'] maps to officer change, polymarket_edge topic:'fed', and fred_series series_id:'UNRATE'. It also clarifies delivery nuances (feed always on, optional email/SMS with verification and cap). This adds value over 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 opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by framing the action as creation and referencing 'pull via recent_alerts' as the consumption path, which is an alternative rather than the subscription itself.

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

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

The description states when to use this tool (to create a persistent subscription) and gives prerequisites ('Requires a Pipeworx OAuth account; anonymous + BYO cannot persist subscriptions'). It also contrasts with pulling data directly via recent_alerts or GET alerts.json, implying this is for proactive monitoring, not on-demand retrieval. However, it does not explicitly compare with sibling tools like list_subscriptions or unsubscribe, or provide when-not-to-use guidance.

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

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

Annotations already declare readOnly, openWorld, and idempotent behavior. The description adds valuable context beyond that: it returns category-bucketed examples with live tool/argument shapes, supports optional topic filtering, and serves as a gateway to meta-tools. This gives the agent a clear model of what to expect.

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 realistic user queries but is written as one long run-on sentence that lists many categories and examples. The content is useful for onboarding, but it could be organized into shorter sentences or bullets 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's simple interface (one optional parameter, no output schema) and rich annotations, the description covers all necessary context: when to use it, how to invoke it, what it returns, and its role relative to meta-tools. It is complete for an agent's decision-making.

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

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

The schema fully documents the single optional parameter, including allowed values and the omit-for-cross-category default. The description reinforces this by giving examples (finance, pharma, betting) but does not add new format or syntax details, 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 a specific verb+resource: it suggests example questions and acts as the onboarding entry point for new Pipeworx users. It distinguishes itself from siblings by explicitly saying 'Use this FIRST' and by describing its unique output: category-bucketed example questions with exact tool and argument shapes.

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

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

It provides explicit when-to-use guidance ('Use this FIRST when you do not yet know what Pipeworx can do for you') and explains the two invocation modes (no arguments for full spread, or pass topic to focus). It does not name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Beyond annotations, the description adds critical behavioral details: ownership enforcement and the fact that rows are deactivated rather than deleted, preserving historical events for recent_alerts. These details complement annotations (idempotent, non-destructive) and help the agent anticipate side effects.

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, each earning its place: action, ownership constraint, and side-effect behavior. Information is front-loaded, with 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?

For a simple one-parameter tool with no output schema, the description covers the essential behavioral aspects (cancellation, ownership, deactivation) and even addresses downstream impact on recent_alerts. It doesn't describe success/failure outcomes, but that is likely inferable from the deactivation behavior, making it sufficiently complete for typical use.

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

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

The schema already provides 100% coverage for the 'id' parameter with a clear description ('Subscription id (uuid) returned by subscribe'). The tool description merely says 'by id' without adding further semantic detail, so it meets the baseline but adds no extra value beyond the schema.

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

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

The description starts with a specific verb 'Cancel' + resource 'subscription' + method 'by id', clearly distinguishing it from siblings like subscribe and list_subscriptions. It states exactly what the tool does.

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 clear context: cancellation by id, ownership enforced (you can only cancel your own subscriptions). This gives an implicit constraint on usage. Does not explicitly name alternatives or when-not-to-use scenarios, but the context is sufficiently clear for a simple mutation.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: it mentions the SEC EDGAR + XBRL fast path with 'exact percent-delta math', the grounded pipeline fallback with verbatim evidence, and the return of a verdict and citation. It does not contradict annotations and enriches the agent's understanding of what happens during execution.

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

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

Although the description is long, every sentence earns its place: it front-loads with high-signal trigger phrases, then covers usage, routing, return values, and a value proposition (replacing 4–6 calls). There is no fluff or repetition of schema details, making it dense yet 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?

The tool has 2 parameters with full schema coverage, no output schema, and moderate complexity. The description compensates for the missing output schema by specifying return values (verdict, actual value, citation, reasoning). It also covers the key decision tree (financial vs. other claims), data sources, and a concrete use case (tolerance for hallucination detection), making it complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by providing concrete examples for the 'claim' parameter and by explaining the 'tolerance_pct' parameter's purpose ('set 1–2 for hallucination detection'). This added guidance helps the agent choose appropriate values, earning a 4.

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

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

The description opens with explicit natural-language triggers ('Is it true that…', 'fact check', 'verify the claim that…') and states a specific verb+resource: 'natural-language claim verification against authoritative sources'. It clearly distinguishes itself from sibling research tools by focusing on verdict-based fact-checking with a structured SEC EDGAR fast path and a grounded fallback pipeline, making it highly specific and differentiated.

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 whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic (company-financial claims vs. any other claim), which gives strong contextual guidance. However, it does not explicitly name alternative tools or state when not to use it, though the 'replaces 4–6 sequential calls' wording implies it is the consolidated choice.

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