Destatis

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds return structure (per-model fields + combined view), reveals cost implications (free default vs BYO key), and explains that _apiKey passes through to Anthropic. No contradictions.

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

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

Description is 4 sentences, front-loaded with the main action and output. Each sentence adds information without redundancy. Could be slightly more concise but still well-structured.

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

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

Given moderate complexity (4 parameters, no output schema), the description covers purpose, parameters, output structure, and use cases. Missing error handling or rate limits, but readOnly/idempotent hints mitigate that need.

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% (all parameters have descriptions). The description adds value by clarifying default model, the effect of _apiKey, and the purpose of 'context' parameter for disambiguation, going beyond schema descriptions.

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

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

The description clearly states the action (probe), resource (LLMs about an entity), and output (visibility score per model). It explicitly mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) that distinguish it from sibling tools like 'ask_pipeworx' 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 explains when to use (for visibility scoring), the default free model, and the requirement for an API key for Anthropic. It implies appropriate contexts but does not explicitly state when not to use or name alternatives.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context that the tool routes questions to 3,735 tools across 882 sources and returns structured answers with stable citation URIs (pipeworx://). This goes beyond annotations and helps the agent understand the tool's 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 front-loaded with the key instruction 'PREFER OVER WEB SEARCH' and efficiently covers purpose, usage, and examples. It is not overly verbose; every sentence serves a purpose. Slightly long but well-structured.

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

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

Given the tool's complexity (access to thousands of sources) and simple schema (just a question), the description is complete. It explains what the tool does, when to use it, and what the output looks like (structured answer with citations). No output schema exists, but the description covers the return value adequately.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing three concrete examples of questions and explaining that the tool accepts multiple aliases (query, q, prompt, etc.). This enhances understanding beyond the schema's property descriptions.

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

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

The description clearly states the tool's purpose: answering factual questions about current or historical data from authoritative sources. It distinguishes itself from web search explicitly and lists many types of data it handles, such as SEC filings, FDA drug data, and economic statistics. The verb 'ask' and resource 'Pipeworx' are clear.

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

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

The description gives explicit usage guidance: 'PREFER OVER WEB SEARCH' for specific types of questions, and lists trigger phrases like 'what is', 'look up', 'find', etc. It even says to use it 'even if web search could also answer it', providing strong direction on when to invoke this tool over siblings.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds the extra LLM call cost, explicit refusal reasons, and the extraction-only mechanism. No contradiction with annotations.

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

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

Four sentences, front-loaded with purpose, every sentence adds distinct value (purpose, behavior, return format, usage guidance). Efficient and clear.

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

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

Without an output schema, the description fully specifies the return structure ({answer, evidence, ...}, refusal reasons) and failure modes. Covers all operational aspects needed for reliable agent invocation.

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

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

Schema coverage is 100% with aliases documented. The description confirms that 'question' accepts natural language but adds no new constraints or formatting beyond the schema. Baseline 3 applies.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, distinguishing it from the sibling tool 'ask_pipeworx'. It uses specific verbs ('ask', 'extracts', 'fetches') and identifies the resource ('Pipeworx' and its grounded variant).

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

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

Explicitly states when to use ('when an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to use ('prefer ask_pipeworx for casual lookups'), directly addressing 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 extensively details behaviors: resolver contract, parent_event extraction, news fallback, safety short-circuits, wide-spread liquidity, and resolution-rule risk. Annotations already tagged readOnly, idempotent, and non-destructive, and the description adds far deeper transparency 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 very lengthy and covers many edge cases and technical details. While comprehensive, it could be more concise by front-loading the core purpose and deferring verbose examples to after the key behavioral notes.

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

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

Given the complexity (multi-source fan-out, various classifiers, response shapes, safety mechanisms), the description is thorough. With no output schema, it compensates by detailing result fields and error states, making it complete for an AI agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description provides input examples but adds minimal new parameter semantics beyond what's in the schema (e.g., depth is explained only implicitly through fan-out examples).

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, with specific input types (slug, URL, question text) and outputs (evidence packet, comparison). It is specific but does not explicitly differentiate from sibling Polymarket tools like polymarket_edges or polymarket_arbitrage.

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

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

The description provides explicit use cases (should I bet, what does data say, is there edge) and examples. It does not explicitly say when not to use or compare to alternatives, but context signals suggest it is for one-off bets rather than ongoing tracking.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds value by detailing data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), fiscal year handling, and result sorting, which go 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 front-loaded with example queries and is mostly concise. Every sentence contributes value, but it could be slightly shorter without losing clarity.

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

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

Given no output schema, the description adequately explains the return format (paired data, citation URIs, sorted by primary metric). It covers both entity types and data sources, making it complete for the tool's purpose.

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

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

With 100% schema coverage, the description still adds significant meaning: it explains what data is retrieved per type (latest 10-K metrics for companies, adverse-event counts for drugs) and specifies value format (tickers/CIKs for companies, names for drugs).

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

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

The description uses specific verbs ('compare', 'side-by-side comparison') and identifies the resource ('2–5 companies or drugs'). It clearly distinguishes from sibling tools like entity_profile by emphasizing parallel comparison over sequential lookups.

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

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

It explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing strong when-to-use guidance. However, it does not name the alternative (entity_profile) for single-entity lookups, so it's not a full when-not-to-use.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds key context: grounded answers with gaps, no invention, account needed, paid tier for thorough, latency expectation.

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

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

Description is packed with information in one paragraph, front-loaded with purpose. Slightly verbose but every sentence earns its place.

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

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

Despite no output schema, description explains return structure (findings packet with evidence, sources, gaps, citations). Also covers authentication, pricing, latency, and usage context.

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

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

Schema covers both parameters (100% coverage). Description adds practical meaning by explaining depth values (quick=3, standard=5, thorough=8) and that broad questions are fine.

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

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

Description clearly states it performs multi-source research in one call, decomposing questions and routing to many tools. It distinguishes from sibling ask_pipeworx.

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

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

Explicitly advises use for broad/multi-part questions and points to ask_pipeworx for single lookups. Also mentions account and plan requirements.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it returns matching table codes and titles, which is consistent but does not significantly expand behavioral insight 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 concise, front-loaded with the action, then provides examples, usage preference, and return format in a few sentences without redundancy. Every sentence serves a purpose.

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

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

Given no output schema, the description adequately explains the return format (table codes + titles) and how to proceed (use destatis_table). It could mention error handling or pagination, but the limit parameter and example help. The sibling tool link is useful.

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 describes all three parameters with 100% coverage. The tool description only implicitly mentions the 'term' parameter via examples and does not add new semantic value for 'limit' or '_apiKey'. A score of 3 is appropriate as baseline when schema is sufficient.

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 searches Destatis GENESIS for data tables by keyword, lists example topics, and distinguishes from web search and the sibling tool destatis_table by specifying that results are table codes to be used with the latter.

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 recommends using this tool over web search for German official statistics and directs the user to pass the returned code to destatis_table for data. It does not explicitly state when not to use it, but the context is clear enough.

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

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

Annotations already indicate read-only, open-world, and idempotent hints. The description adds useful behavioral context: the return includes values, dimensions, title, and geographic coverage. It does not contradict 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 sentences: core function with examples, return specification, and geographic scope. No redundant information; every sentence adds value.

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

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

For a two-parameter tool with no output schema, the description fully covers what the tool does, how to use it (including dependency on destatis_search), and what is returned. No gaps remain.

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

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

Schema coverage is 100% and describes both parameters. The description adds concrete examples for table_code and clarifies the apiKey is optional, which goes beyond the schema's description. The impact of parameters is sufficiently explained.

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 fetches data from Destatis GENESIS using a table code, with explicit examples like "12411-0001". It distinguishes from sibling destatis_search by instructing users to get codes from that tool.

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

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

The description explains when to use the tool (after obtaining codes from destatis_search) and mentions the return scope (Germany-wide and by Land). However, it does not explicitly state when not to use it or list alternatives beyond the search sibling.

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, destructiveHint=false. The description adds value by explaining that results include 'full input schemas (with curated examples)' and that 'each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations to clarify output 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 tightly packed with information, front-loaded with the core action 'Find tools by describing the data or task.' Every sentence contributes: domain list, return format explanation, usage guidance. No wasted words, and the structure is logical.

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

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

Given the tool's role as a discovery tool with multiple parameters and no output schema, the description is remarkably complete. It explains what it does, when to use it, what it returns (top-N tools with names, descriptions, and schemas with examples), and provides example queries. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical examples like 'look up FDA drug approvals' and 'analyze housing market trends' that are not in the schema. It also lists aliases for query (q, task, search, description), enhancing understanding beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the action (find/discover), the resource (tools), and distinguishes from siblings by noting it returns full input schemas for direct invocation. The list of example domains (SEC filings, FDA drugs, etc.) adds specificity.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance. However, it could be stronger by explicitly contrasting with specific sibling tools like deep_research for in-depth analysis.

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 non-destructive. The description adds behavioral details: fans out across multiple APIs, soft-fails for USPTO sunset, and lists specific return fields. This adds significant value beyond annotations.

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

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

The description is fairly long but front-loaded with example queries and a clear purpose statement. Every sentence adds value, but some details (e.g., USPTO sunset) could be more concise. Still, it's efficient for the amount of information.

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

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

No output schema, but the description enumerates all return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). For a complex profile tool, this provides sufficient completeness for an agent to understand what to expect.

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 parameters are documented. The description adds context: type enum is currently only 'company', value accepts ticker or CIK (not names). This clarifies usage beyond schema definitions, earning a higher score than baseline.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call.' It lists example queries and specifics of data sources (SEC, XBRL, USPTO, news, GLEIF) and return fields. This distinguishes it from siblings like resolve_entity (name resolution) and compare_entities (comparison), making 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?

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also advises using resolve_entity first if only a name is available. This provides clear when-to-use and when-not-to-use guidance, with a specific alternative for name inputs.

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

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

The description discloses deletion behavior (destructive) and mentions clearing sensitive data. Annotations already indicate destructiveHint=true, so the description adds context about why deletion is useful. Could further clarify if deletion is permanent but given annotation coverage 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?

Two sentences with no wasted words. Front-loaded purpose followed by usage guidance. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage, and integration with sibling tools. Complete and self-contained.

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

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

Schema coverage is 100% with a clear description for the only parameter ('key'). The description adds no new details beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool deletes a memory by key, using specific verb 'delete' and resource 'memory'. It distinguishes from siblings 'remember' and 'recall' by referencing them as alternatives for storing and retrieving.

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' scenarios: stale context, task completion, clearing sensitive data. Also suggests pairing with 'remember' and 'recall', which gives clear guidance relative to sibling tools.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds behavioral context: it fetches the page, extracts content, and outputs markdown. No contradictions with annotations.

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

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

The description is two efficient sentences plus a bullet list of use cases—no fluff, information front-loaded.

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

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

Despite lacking an output schema, the description fully explains the output format (standard llms.txt markdown, ready to drop at site-root/llms.txt) and the process, making it self-contained.

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

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

Schema coverage is 100%, so schema fully documents both parameters. The description restates the default and max for max_links but adds no meaning beyond what the schema already provides.

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

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

The description uses a specific verb ('Generate'), identifies the resource ('llms.txt file for any URL'), and clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on AI crawler indexing.

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

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

The description explicitly lists three use cases ('getting a client's site indexed', 'drafting for your own project', 'auditing a competitor'), providing clear context. However, it does not mention when not to use it or explicitly differentiate from alternatives beyond 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?

Annotations (readOnlyHint, idempotentHint, destructiveHint) already disclose mutability. The description adds value by detailing returned fields and the optional include_inactive parameter. No contradiction with annotations.

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

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

Two sentences with no wasted words. First sentence states purpose and output, second gives usage guidance. Front-loaded and efficient.

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

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

For a simple list tool with one optional parameter and informative annotations, the description covers purpose, output fields, and usage. No output schema needed as return values are described.

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

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

Schema coverage is 100% with a clear description for include_inactive. The description adds context about 'active subscriptions' but does not enhance parameter meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description specifies 'List the caller's active subscriptions' and lists returned fields (id, type, params, created_at, last_fired_at, fire_count), clearly distinguishing it from siblings like subscribe and unsubscribe.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides clear context, though does not explicitly mention when not to use.

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

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

Discloses rate limits (5 per identifier per day), cost (free, no quota consumption), and processing (team reads daily digests). Annotations provide no contradictions; the description adds valuable behavioral context.

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

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

The description is well-structured with front-loaded purpose, conditional usage, and concise guidelines. Every sentence adds value without redundancy or unnecessary details.

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

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

Given the tool's complexity (3 parameters, nested object, no output schema), the description covers purpose, usage, rate limits, and response handling (team reads daily). No gaps remain for effective invocation.

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

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

Schema coverage is 100% with detailed descriptions. The description reinforces parameter usage by advising on what to include in 'message' (e.g., specific tool, error, missing data), adding value beyond the schema.

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

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

The description clearly defines the tool's purpose: sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. It provides specific examples and distinct categories, making it easily distinguishable from sibling tools.

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

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

Explicitly states when to use the tool (e.g., bug reports, feature requests, praise) and what not to do (e.g., avoid pasting end-user prompts). This provides clear context for appropriate usage.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds value by explaining data source (CF analytics-engine), scope (no PII, just counts), and caching behavior (5min-1h), which are not in annotations.

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

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

Punchy first sentence, then bullet-like use cases, then technical notes. No fluff; every sentence adds value. Excellent front-loading.

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

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

For a simple tool with 1 optional param and no output schema, description covers purpose, return content, data source, use cases, and caching. Fully complete.

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

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

Schema covers the 'window' parameter 100% with enum and description. The description further clarifies semantics (shorter windows for hot vs longer for steady-state), adding 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?

Description clearly states the tool returns 'top tools, top packs, and total call volume' over configurable windows, with a specific verb ('returns') and resource ('trending data on Pipeworx'). Differentiates from siblings by focusing on aggregate agent activity.

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

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

Lists three concrete use cases (discovery, confirmation, alignment) that help the agent decide when to use this tool. Lacks explicit when-not-to-use or alternatives, but the context provided is sufficient for a 1-param tool with diverse siblings.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds algorithmic details (monotonicity checks, Jaccard similarity, placeholder filtering, fill check) that go beyond annotations, with no contradictions.

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

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

The description is detailed and informative, but slightly lengthy. However, every sentence adds value, and the structure (requirement first, then modes, then edge cases) is logical.

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

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

Despite no output schema, the description explains the response structure (opportunities[], partition_check, fill_check details) and covers edge cases (no args, low similarity, placeholder filters). References related tool for custom sizing.

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

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

Schema coverage is 100% with descriptions; description enriches meanings with examples (e.g., 'fed-decision-may-2026'), explains mode behavior, and clarifies that full URLs are accepted.

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. It distinguishes two modes (event and topic) and contrasts with sibling tools like polymarket_edges.

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

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

Explicitly requires one of event or topic, warns call with no args fails. Recommends event for specific markets and topic for cross-event scanning. Provides when-not-to-trade guidance (realizable edge ≤ 0) and references polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds extensive behavioral details: how three opportunity segments work, data sources (FRED, GDELT), output fields (edge_pp_net, kelly_fraction, diagnostics), filtering knobs, and caching behavior ('Cached 1h at the KV level'). 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 very long and dense, though structured with sections and parenthetical notes. It front-loads the purpose but includes many technical details that could be simplified. Given the tool's complexity, some verbosity is justified, but conciseness could be improved.

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

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

Given the tool's complexity (9 parameters, no output schema) the description is remarkably complete. It explains output structure (by_segment, fed_candidates, _diagnostics), return fields, caching policy, and algorithm details. Every aspect is covered, making the tool fully usable without external documentation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context beyond schema by explaining the roles of knobs like min_liquidity, max_spread_pp, and min_partition_leg_kelly within the overall edge-discovery process, providing meaningful added value for parameter understanding.

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

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

The description clearly states the tool's purpose: scanning top Polymarket markets to find opportunities where Pipeworx data disagrees with market price. The verb 'scan' and resource 'Polymarket markets' are specific and differentiate it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description includes explicit usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' While it doesn't provide explicit exclusions or comparisons to alternative tools, the context is clear and helpful for an agent deciding when to invoke this tool.

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

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

The description adds significant behavioral context beyond the annotations: it explains that the tool reads snapshots, that gaps occur when no cache-miss, that history is bounded by TTL, and that decay numbers are from daily closes net of slippage. 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 a single, well-structured paragraph that packs essential information without wasted words. It front-loads the core concept and then details response structure and limitations.

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

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

Given the tool has only two optional parameters, no output schema, and no nested objects, the description is thorough. It explains the response fields, data sources, and constraints, providing complete context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds meaning: it specifies default values and valid ranges (days clamp 2-30), explains 'window' as snapshot family, and describes how parameters affect the response (e.g., latest snapshot used).

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 explains the tool's purpose: edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge age and trend, distinguishing it from the sibling tool 'polymarket_edges' which likely provides current edges.

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

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

The description implies when to use it (to assess edge age and decay) and mentions limits (60-day TTL, decay from daily closes). It does not explicitly state alternatives or when not to use it, but the context signals list siblings that provide different views.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds critical behavioral context: return fields like verdict (clean/degraded/cannot_fill), thin_legs, forced_directional_risk, and the risk of partial fills. 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 well-structured with bolded key terms (SINGLE-MARKET, BASKET) and clear sections. It front-loads the required parameter constraint. Could be slightly more concise, but every sentence adds important context.

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

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

No output schema exists, so the description fully explains return fields: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk. Covers both modes comprehensively.

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 schema already documents parameters. The description adds value by clarifying default side detection in basket mode (auto based on partition sum) and the meaning of size_usd as 'settlement notional' and shares per leg.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' for two modes (single-market and basket), differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicit guidelines: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns about partial basket fills converting arbitrage into unhedged directional positions.

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 (readOnlyHint, openWorldHint, etc.) to disclose detailed behavior: response structure, safety fields (compatibility_warning, temporal_alignment), and reasons why spreads may be meaningless (different bet shapes, temporal gaps). It fully informs the agent about edge cases and limitations.

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

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

The description is relatively long but necessary given the tool's complexity. It is well-structured: introduction, two modes, response details, safety fields. Every sentence adds value, though it could be slightly more compact for a quick scan.

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

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

Despite having no output schema, the description thoroughly explains the return values: leg-by-leg prices, matched spreads, compatibility warning, temporal alignment, and skip counters. This provides a complete picture for an agent to interpret results correctly.

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

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

With 100% schema coverage, the baseline is 3. The description adds significant value by explaining how the three parameters relate to the two modes, including examples and override behavior. This contextual richness justifies a higher score.

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

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

The description clearly states it calculates the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from similar tools like polymarket_arbitrage by specifying the two-venue nature and providing detailed mode explanations.

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

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

The description explicitly explains the two modes (topic shortcuts vs explicit pairing) and when each is appropriate. It also warns that many pre-mapped topics may not yield tradeable spreads due to compatibility warnings, providing practical guidance on expectations. It does not directly compare to sibling tools but gives sufficient context for usage.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds scoping details (identifier-based) and clarifies non-destructive nature 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?

All sentences are purposeful and front-loaded, though slightly denser than necessary; no 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?

Covers purpose, parameters, usage, and scoping well; return behavior is implicit but not explicitly described (e.g., value or list). No missing critical info.

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

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

Schema coverage is 100%; description adds behavioral context for the key parameter (omit to list all keys) that goes beyond the schema's basic description.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, with specific verb-resource pairing and examples that distinguish it from 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?

Provides explicit when-to-use guidance ('look up context the agent stored earlier') and how to use (omit key to list), including pairing with remember and forget.

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

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

Annotations declare readOnlyHint=true, but description states setting mark_read:true flags events as read, which is a state modification. This creates a contradiction between description and annotations, severely undermining transparency.

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

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

Four sentences, front-loaded with purpose, followed by return details, filtering, and alternative access. No redundant words.

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

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

Despite no output schema, description adequately describes returned fields. Covers filtering, mark_read side effect, and alternative access. Lacks explicit pagination or limit behavior, but sufficient for a polling 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. Description adds value by explaining filtering with type and since, and the effect of mark_read on subsequent calls (only newer events), which goes beyond the raw 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 verb (pull) and resource (fired events from subscription feed), and specifies what each event carries (source, citation_uri, raw payload). It distinguishes from sibling tools like list_subscriptions by focusing on events.

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 filtering options (type, since), explains mark_read behavior, and mentions polling suitability. Also gives an alternative access method (HTTP GET). Missing explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it fans out to multiple APIs, describes specific API details (GDELT preferred, GNews fallback, USPTO soft-fail), and explains the return structure (changes[] grouped by source, citations). 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 slightly long but every sentence adds value. It is front-loaded with example queries. Could be slightly more concise, but the density of useful information justifies the 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 no output schema, the description clearly states the return structure: 'Returns structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It covers all sources, fallback, parameter format, and contrasts with sibling. Annotations cover safety. Complete for the tool's complexity.

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

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

Schema coverage is 100% (all parameters described). The description enriches meaning: 'since' explains ISO date and relative shorthand with examples and typical usage; 'value' specifies ticker or CIK; 'type' is enum with only company. This goes beyond the schema but schema already covers basics.

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

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

The description clearly states the tool provides a change feed for a company over a recent time window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes from sibling 'entity_profile' by specifying when to use that instead.

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 example queries ('What's new with X', 'latest on Y') and tells when not to use it ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior (GDELT→GNews) and acceptable 'since' formats.

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 idempotent and non-destructive. Description adds critical context: scoped by identifier, authenticated users persistent, anonymous 24hr retention. No contradiction with annotations.

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

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

Four sentences, front-loaded with purpose. Every sentence adds value: purpose, usage scenario, scope details, and pairing hints. No wasted words.

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

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

Given two required parameters, no output schema, but description explains lifecycle, scoping, and pairing with recall/forget. Adequately complete for a memory tool.

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

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

Schema description coverage is 100%, so both 'key' and 'value' are described. Description adds examples of key naming conventions (e.g., 'subject_property') but does not add significant meaning beyond what schema provides. Baseline 3 is appropriate.

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

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

Description clearly states 'Save data the agent will need to reuse later' and lists concrete examples (resolved ticker, target address, user preference). It distinguishes from sibling tools 'recall' and 'forget' by mentioning them as partners.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and warns against looking up again. Provides context about session scope and persistence. Could be slightly more explicit about when not to use (e.g., one-time data).

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds that each call cascades through several endpoints internally, replacing 2-3 manual lookups—useful behavioral context beyond annotations. No contradiction with annotations.

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

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

Description is front-loaded with trigger phrases and examples, covering purpose, types, return values. Slightly verbose but efficient; every sentence adds value. Could condense slightly, but structure is logical.

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

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

Given no output schema, the description fully explains return values (ticker+CIK+URI for company; RxCUI+ingredient+brand+URI for drug). Also notes cascading internal calls. For a lookup/resolution tool with two params and 100% schema coverage, this is complete.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: for 'company' it accepts ticker, CIK, or name with auto-disambiguation; for 'drug' it accepts brand or generic name. This goes beyond the schema's enum and brief description.

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

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

The description clearly states it resolves names to canonical/official identifiers, with specific examples ('What's the ticker for...', 'find the CIK for...'). It uses a specific verb ('resolve') and resource ('entity name to identifier'), and distinguishes itself from siblings like 'entity_profile' by emphasizing ID retrieval for use as input to other tools.

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

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

Explicit guidance to use when having a name but needing an ID ('Use FIRST whenever...'). Describes supported types with examples. No explicit when-not-to-use, but the context of sibling tools (e.g., 'entity_profile' for details after ID) makes usage clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it 'probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and describes the return format (ranked list with score, confidence, signal density per entity). This goes beyond annotations without contradiction.

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

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

Three well-structured sentences. The first sentence clearly states purpose, the second explains the process, and the third gives a use case example. Every sentence earns its place with no redundancy. Front-loaded and efficient.

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

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

No output schema exists, so the description must explain return values, which it does: 'ranked list with score, confidence, signal density per entity.' With 4 parameters all described in schema and no nested objects, the description is complete enough for an agent to understand input and output without needing extra context.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning: the first entity is treated as the 'subject' for narrative, rest as competitors, and clarifies that omitting models defaults to only workers-ai. This provides useful context beyond the schema's parameter descriptions.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side,' specifying the verb 'compare' and the resource 'AI visibility across entities.' It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison) by detailing its composite nature of probing each entity with ai_visibility_check and ranking results.

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

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

The description explicitly states usefulness 'for competitive AI-marketing audits' and gives an example question. While it does not explicitly say when not to use, it implies that single entity checks should use ai_visibility_check, and the sibling list includes that tool. This provides clear context for usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeouts. This contextualizes the behavior 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 lengthy but well-structured, with a clear opening line summarizing the tool's value, followed by details on usage, limitations, and behavior. It could be slightly more concise, but every sentence serves a purpose.

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

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

Given the tool's complexity (multi-source, output fields, potential timeouts, partial failures), the description is remarkably complete. It explains the output structure (summary block, per-advisory detail, links, alternative versions) without needing an output schema. The context about NPM-only and fallback options for other ecosystems adds completeness.

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 addionally clarifies that scoped packages are accepted (e.g., '@types/node') and that version defaults to latest when omitted. This enriches the schema information.

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

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

The description clearly states the tool is a composite check for npm packages, specifying the verb 'scan' and resource 'dependency', and lists the exact data sources (deps.dev, bundlephobia) and output fields. It distinguishes itself from siblings by being specific to npm packages and a one-call aggregation.

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: 'is X safe / popular / small' or 'what does adding lodash cost me'. It also explicitly states the ecosystem limitation ('NPM ecosystem only in v1') and directs users to other tools for other ecosystems ('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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details beyond these: explains the embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), character offset feature, and the 200K char cap with truncation flagging. This provides a solid behavioral model for invocation.

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

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

The description is concise and well-structured: first sentence states purpose, second provides usage guidance and pairing, third gives technical details. Every sentence adds unique value 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?

Despite no output schema, the description explains return format (top-N passages with character offsets and similarity scores). It also covers truncation behavior (200K cap, flagged). Given the tool's complexity (semantic search with chunking), this is complete and enables proper invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the 'text' parameter as 'the text you already pulled,' providing natural-language query examples for the 'query' parameter (e.g., 'supply-chain risk'), and reminding of default and range for 'limit'. These examples and clarifications exceed 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 begins with 'Semantic search INSIDE a fetched record,' clearly stating the verb (search), resource (fetched record), and scope (inside). It provides concrete examples like SEC 10-K body, article, long tool result, and distinguishes from sibling tool ask_pipeworx_grounded by explaining the pairing workflow.

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: 'when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also mentions pairing with ask_pipeworx_grounded for a suggested workflow. While it doesn't list explicit 'when not to use' scenarios, the context is clear enough for an agent to decide.

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

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

Discloses important behavioral details beyond annotations: account requirement, subscription types, delivery channels, webhook signing, SMS caps, phone verification. Consistent with annotations.

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

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

Well-structured with action first, then requirements, types, delivery. Though lengthy, each sentence adds value for a complex tool.

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

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

Comprehensive coverage: purpose, requirements, types, delivery channels, return value, webhook signing. No output schema but return value is stated. Complete for the tool's complexity.

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

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

Adds rich semantics for all parameters: examples for each subscription type, delivery options with formatting rules. Schema coverage is 100%, and description significantly enhances understanding.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns the subscription id. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

Provides clear context: requires Pipeworx OAuth account, types, delivery options. Does not explicitly state when not to use but implies alternatives through sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about what the tool returns (example questions with tool+argument shapes, drawn from a live catalog) and how calling with/without topic changes behavior. This adds meaningful 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 somewhat verbose but front-loaded with the core purpose. It efficiently covers key points: the trigger phrases, the return content, and usage instructions. A minor trim for conciseness would improve it, but it is well-structured and clear.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is thorough. It explains the use case, what it returns (category-bucketed example questions with tool shapes), how to invoke it (no args vs topic), and its role as an onboarding entry point. No significant gaps.

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

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

With 100% schema description coverage, the schema already documents the topic parameter. However, the description adds value by listing possible values for topic (finance, pharma, etc.) and explaining their effect ('focus' vs 'cross-category spread'). This enriches the parameter semantics.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions for Pipeworx, serving as an onboarding entry point. It uses specific verbs like 'returns' and 'use this FIRST', and distinguishes itself from siblings like ask_pipeworx and discover_tools by positioning itself as the starting point for exploration.

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

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

The description provides explicit guidance on when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional topic parameter and the default behavior. However, it does not explicitly state when not to use it, but the context makes it clear.

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

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

Annotations indicate non-readOnly and non-destructive. The description adds behavioral context: ownership check and soft-delete behavior (deactivated, not deleted), which would not be inferred from annotations alone.

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

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

Two sentences, front-loaded with the action, no waste. Every sentence earns its place.

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

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

For a simple tool (1 param, no output schema) with rich annotations, the description covers purpose, ownership, and behavioral effect completely.

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

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

Schema coverage is 100% for the single parameter 'id', which already includes a description. The tool description does not add further parameter details, achieving baseline.

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

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

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

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

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

Ownership enforcement ('you can only cancel your own subscriptions') and post-cancel behavior (deactivated, not deleted) provide clear guidance, though it doesn't explicitly list when not to use.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint, so safety is clear. The description adds value by detailing the output format (verdict types, citation, percent delta) and explaining efficiency gains over sequential calls, which helps the agent understand behavior beyond annotations.

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

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

The description is a single paragraph that efficiently conveys all key information: usage examples, domain, output, and efficiency. It is front-loaded with examples and avoids unnecessary verbosity, though it could benefit from slightly more structured formatting.

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

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

Given the tool has a single parameter and no output schema, the description sufficiently covers inputs, outputs (verdict types, citation, percent delta), and scope limitations. The explanation of how it replaces multiple sequential calls provides complete context for an AI agent to understand its value and use.

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

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

Schema description coverage is 100% for the single required parameter. The description goes beyond by providing natural-language examples and clarifying the input format, thus adding meaningful context that aids correct parameterization.

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 does natural-language claim verification against authoritative sources, provides example queries, and specifies the domain (company-financial claims). It distinguishes itself from sequential alternatives, making the purpose clear 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 clearly states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It also specifies the scope (company-financial claims). While it does not explicitly state when not to use, the context is sufficient for correct selection.

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