Destatis

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by noting the default model is free, that an API key is needed for Anthropic with pass-through billing, and describes the return structure (per-model + combined). 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 the core purpose. Every sentence adds essential information (purpose, default model, key requirement, return format, use cases). No fluff or redundancy.

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

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

With no output schema, the description adequately describes return values (per-model and combined view). It covers prerequisites (_apiKey for Anthropic), default behavior, and use cases. Missing error handling or limitations, but for a probing tool this is sufficient.

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

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

Schema coverage is 100%. The description explains the entity parameter (what to ask about), models (default workers-ai, optional Anthropic with _apiKey), and context for disambiguation. This adds practical meaning beyond the schema descriptions, though the schema already does a good job.

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 probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It distinguishes from sibling tools like ask_pipeworx or deep_research by focusing specifically on AI visibility metrics rather than general Q&A or research.

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

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

Explicit use cases are given: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not discuss when to avoid this tool or compare it to the sibling scan_competitor_ai_presence, which may overlap.

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 readOnly, openWorld, idempotent, and destructive hints. The description adds useful behavior context: it routes to 5,564 tools, fills arguments, returns pipeworx:// citation URIs, works on every tier, and is described as 'one fast call'. It does not mention auth or rate limits, but these are not critical given the annotations.

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

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

The description is long but front-loaded with the primary directive and well-structured into use-case, examples, and alternatives. There is minor redundancy ('START HERE' and 'default entry point' say the same thing), but every sentence overall earns its place for a general-purpose 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?

The description is remarkably complete for a complex routing tool: it covers purpose, how it works, when to use, alternatives, examples, output format (citation URIs), and breaking-news handling. No output schema exists, but the citation URI mention sufficiently explains the return value.

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

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

Schema coverage is 100%, and the schema documents the 'question' parameter and its aliases with examples. The description's examples illustrate acceptable inputs but add no new semantic meaning beyond the schema, so baseline 3 is appropriate.

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

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

Clearly states it routes factual questions to 5,564 tools across 1,462 verified sources and returns structured answers with citation URIs. It explicitly differentiates from siblings by naming ask_pipeworx_grounded and deep_research as step-up alternatives, making the purpose unambiguous.

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

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

Provides explicit 'PREFER OVER WEB SEARCH' guidance and lists trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') with concrete examples. It also states when NOT to use it by directing to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for multi-part questions, and covers breaking-news special cases.

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 destuctiveHint=false, so the description does not need to restate safety. The description adds valuable context about the experimental nature, candidate testing, and current equivalence to the stable router. However, it does not disclose any additional behavioral traits beyond what annotations provide, such as rate limits or error handling, making it adequate but not exceptional.

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-loading the key point (beta version, identical to stable), then provides context about the candidate testing, current state, and usage guidance in a clear two-sentence structure with zero wasted words.

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

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

Given the tool's complexity (universal router with many tools) and the absence of an output schema, the description covers the essential context: its identity as a beta, its current state, and how to use it. It could optionally mention expected response format or error behavior, but for a router tool that delegates to other tools, the description is adequately complete for an agent to use it correctly.

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

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

Schema description coverage is 100%, and the description does not add much beyond: it mentions the same arguments as the stable router. The description does not elaborate on parameter semantics (e.g., format, constraints) beyond what the schema already covers with aliases. The baseline of 3 is appropriate as the schema does the heavy lifting.

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 tool name and description clearly state it is a beta version of 'ask_pipeworx', an identical universal router with the same set of 5,564 tools, arguments, and response shape. The description explicitly distinguishes its purpose from the stable 'ask_pipeworx' by highlighting it is the experimental edge for candidate routing improvements.

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

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

The description provides explicit guidance on when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the context of no active candidate currently, so it matches the stable version exactly, and clarifies its fallback behavior ('Falls back to nothing — this IS a full working router'). This clearly distinguishes from the sibling 'ask_pipeworx' and 'ask_pipeworx_grounded'.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description reveals: it makes one extra LLM call, returns structured refusals with specific reasons, uses only tool result for extraction, and provides precise response format {answer, evidence, confidence, source, etc}. No contradiction with annotations.

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

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

Every sentence earns its place: first defines core purpose and process, then details output and refusal cases, then specifies when to use with concrete examples, and ends with cost tradeoff. No redundancy. Front-loaded with key idea. Length is justified given complexity.

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

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

Despite no output schema, the description fully specifies the return structure (answer, evidence, confidence, source, etc.) and all refusal reasons. Input parameter is clear, usage guidelines are explicit, and behavioral details (cost, grounding) are covered. Nothing is missing for an agent to correctly select and invoke this 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% (all parameters documented as aliases for question). The description does not add new semantic detail about the parameter format beyond what the schema provides. It implies the kind of inputs (high-stakes questions) indirectly via usage context, but this is not parameter-level explanation. Baseline 3 is correct.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and explains the process: picks the right tool, fetches data, extracts answer only from the tool result. It distinguishes itself from ask_pipeworx by noting the extra LLM call and grounded extraction. Specific use cases (financial verdicts, legal claims, etc.) further clarify purpose.

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

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

Explicitly tells when to use ('when answer will be quoted, cited, or acted on, and agent must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'), citing the extra cost. It also contrasts with ask_pipeworx by name, fulfilling the when-not/alternatives requirement.

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 behavioral traits beyond annotations, including fan-out logic, resolver contract, low-confidence short-circuiting, closed market handling, illiquid spread warnings, and cancellation rule parsing. It provides crucial operational context for safe tool usage.

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 quite long and dense, though well-structured with section headers. It front-loads the purpose but includes extensive examples and field details. While informative, it sacrifices conciseness for completeness.

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 tools complexity, the description is remarkably thorough, covering edge cases like low-confidence matches, closed markets, wide spreads, and cancellation rules. Since there is no output schema, the description fully explains the response shape 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?

All three parameters have descriptions in the input schema, achieving 100% coverage. The tools description reiterates parameter behaviors (depth levels, include_raw purpose) but adds only limited new meaning beyond what schema already provides.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifying input types (slug, URL, question text) and expected outputs. It effectively distinguishes itself from sibling tools focused on arbitrage or edge tracking.

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

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

The description explicitly states when to use the tool (e.g., 'should I bet on X') and provides examples of fan-out for various bet categories. It does not explicitly state when not to use it, but the usage guidance is clear and practical.

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, destructiveHint. Description adds that results are sorted by primary metric, returns citation URIs, and handles off-calendar fiscal years. Adds useful behavioral context beyond annotations.

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

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

Description is detailed and well-structured with examples, but slightly verbose. Could be trimmed without losing clarity.

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

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

No output schema, but description covers return values (paired data, citation URIs), data sources, sorting, and entity constraints. Adequate for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. Description enriches by explaining values are tickers/CIKs for company and names for drug, max 5 items, and behavior for each type. Goes beyond bare schema.

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

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

Clearly states it performs side-by-side comparison of 2-5 companies or drugs, using specific data sources (SEC EDGAR, FAERS). Distinguishes from sibling tools by noting it replaces 8-15 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries. Gives clear use context but doesn't 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?

The description goes far beyond annotations (which already indicate read-only, open-world, idempotent, non-destructive). It details decomposition into facets, parallel routing, findings packet structure (verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), depth-level behaviors, timing expectations, semantic excerpting, and citation URI resolvability. 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?

While front-loaded with account requirement and alternatives, the description is verbose (multiple paragraphs, includes specific numbers like '5,564 tools'). It could be more concise by grouping related details and trimming redundant clauses. The length reduces scanability for an AI agent.

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

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

Despite lacking an output schema, the description thoroughly compensates by describing the return structure (findings packet, gaps, contradictions, hop field, citation_uri). It covers timing, account tiers, depth behavior, and data source types. For a complex tool, this is complete enough for correct 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 both parameters described. The description adds substantial meaning: expands depth enum values with detailed behavior (quick=3 facets single hop, standard=3 with gap recovery+contradictions, thorough=6 paid with iterative hop), and clarifies that question is natural language and broad/multi-part is fine. This is more than the schema provides.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and explicitly distinguishes it from siblings like ask_pipeworx for single lookups or current news. It uses specific verbs ('decomposes', 'routes', 'returns') and resource identifiers ('structured data sources', 'findings packet').

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: 'Best for broad/multi-part questions over structured data' and clear exclusions: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Also mentions account requirement and alternative if not signed in. No ambiguity.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds that it returns table codes and titles, and explains the optional API key authentication. No contradictions.

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

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

Two sentences, front-loaded with purpose and usage priority. Every sentence adds value. No unnecessary words.

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

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

No output schema, but description explains return values (codes + titles) and directs to destatis_table for data. Sufficient for a search tool in context of its sibling.

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

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

Schema coverage is 100%, and description adds meaningful context: explains keyword examples, limit range (1-50), and the purpose of the _apiKey parameter. Provides examples in the schema.

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

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

Clearly states the tool searches Germany's official federal statistics by keyword, returning table codes and titles. Distinguishes from sibling destatis_table by directing users to pass a code for data retrieval.

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

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

Explicitly says 'PREFER OVER WEB SEARCH for German official statistics,' providing a clear usage context. Mentions the workflow of using destatis_table for data, but does not list alternative tools or when not to use it.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context about returning table content (values across dimensions) plus title, and indicates data scope (Germany-wide and by Land where provided), which goes 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?

Three concise sentences: action, examples, output description. Information is front-loaded and every sentence serves a clear purpose with no redundancy.

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

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

Given the tool's simplicity, full schema coverage, and good annotations, the description covers all necessary aspects: what it does, required input, output format (table content and title), and data scope. No output schema exists, so covering return value is appropriate and done well.

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

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

Schema coverage is 100% (both parameters documented). The description adds value by providing real-world examples, emphasizing that table_code comes from destatis_search, and clarifying that _apiKey is optional. 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 fetches Destatis GENESIS table data by code, provides concrete examples ("12411-0001", "61111-0001"), and distinguishes it from the sibling destatis_search tool by directing users to obtain codes from there.

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

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

The description explicitly mentions using destatis_search to get table codes, giving clear context for when to use this tool. While it doesn't state when not to use it, the guidance is sufficient for correct invocation.

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

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

Annotations already include readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context: returns top-N most relevant tools with full schemas and examples, ready to call directly, no second lookup needed. No contradictions.

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

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

Two sentences, front-loaded with purpose, no wasted words. Could be slightly more structured but very efficient.

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

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

Given 6 params (with many aliases), no output schema, the description covers purpose, usage, return format (top-N with full schemas and examples), and guidance to call first. No gaps for an agent to use correctly.

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

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

Schema coverage is 100%, baseline 3. Description mentions aliases for query but mostly repeats schema info. Does not add significant new meaning beyond what's in the schema 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 finds tools by describing data or task, lists many domains (SEC filings, FDA drugs, etc.), and distinguishes itself from sibling tools as a discovery meta-tool.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for:' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear when-to-use and alternatives implied.

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

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

Annotations already indicate read-only, idempotent behavior. Description adds context: specific returned fields, soft-fail for patents, news fallback chain. No contradictions with annotations.

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

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

Description is dense but well-organized, starting with example queries and covering all key aspects. Could be slightly more concise, but each 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?

Given no output schema, the description comprehensively lists all return fields, fallback behaviors, and limitations (patents sunset). Adequate for an agent to understand what the tool provides.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value by explaining CIK zero-padding and stating names are not supported, which goes beyond the schema.

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

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

The description clearly states the tool's purpose: creating a full cross-source profile of a US public company. It lists specific data sources (SEC, XBRL, USPTO, news, GLEIF) and return fields, distinguishing it from sibling tools like compare_entities and resolve_entity.

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 (holistic view, user asks for 'tell me about X'), recommends preferring over chaining single-source lookups, and advises using resolve_entity first if only a name is available.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds the notion of clearing 'sensitive data' but does not detail behavioral aspects like irreversibility or side effects beyond what annotations already convey.

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

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

The description is two sentences, no unnecessary words. Every sentence serves a purpose: defining the tool and providing usage context.

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

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

For a simple, single-parameter tool with destructive and idempotent hints, the description is sufficiently complete. It covers purpose, usage guidelines, and pairing with sibling tools.

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

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

Schema coverage is 100% and the schema already describes the parameter. The description adds no additional meaning beyond the schema, meeting baseline expectations.

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

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

The description clearly states the action (delete) and resource (previously stored memory by key). It distinguishes from siblings 'remember' and 'recall' by mentioning them as pairs, establishing its unique role.

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

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

The description explicitly lists three use cases: stale context, task completion, and clearing sensitive data. It does not specify when not to use but 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 (readOnlyHint, idempotentHint, destructiveHint) already indicate safe read behavior. Description adds process details: fetches page, extracts title/description/key links, and emits markdown. No contradictions.

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

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

Two sentences plus a concise list of use cases. Front-loaded with action, no redundancy, every sentence adds value.

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

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

Description explains the output format and use case. For a simple 2-param tool with no output schema, it provides enough context for an agent to understand expectations.

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

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

Schema coverage is 100%, both parameters have descriptions. The tool description does not add additional meaning beyond the schema; it merely restates the max_links default and max. Baseline 3 is appropriate.

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

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

The description clearly states it generates an llms.txt file for any URL, for AI crawlers. It specifies the output format (markdown) and distinguishes from sibling tools by its unique purpose.

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

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

Description explicitly gives use cases: getting a client's site indexed, drafting for own project, auditing competitors. It does not mention when not to use or alternatives, but the context is clear.

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

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

Annotations already cover safety (readOnly, idempotent). Description adds value by specifying return fields and scope ('caller's'), going beyond annotations.

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

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

Two sentences, front-loaded with purpose, then return fields, then usage guidance. 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?

No output schema, but description lists return fields. Explains the single parameter and usage context. Complete for a simple list tool with good annotations.

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

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

Schema description coverage is 100% with a clear description for the parameter. Description does not need to add more; 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?

Explicitly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from siblings like 'subscribe' and 'unsubscribe' by listing nature.

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 guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Implies 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 are silent (all false), so the description carries the full burden. It discloses the claim_token workflow (filing without account returns a token; passing it back later reads status), rate limits (5/day/identifier), cost implications (free, doesn't count against quota), and operational details (team reads digests daily, signal affects roadmap). It also sets a content boundary: describe in terms of Pipeworx tools, not end-user prompts. This is rich, non-obvious behavioral context beyond structured fields.

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

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

The description is long but every sentence adds unique information: purpose, use cases, exclusion, naming guidance, token workflow, rate limit, cost, and roadmap impact. It is front-loaded with the core purpose in the first sentence, then layers constraints and mechanics. No filler or redundancy.

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

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

For a feedback-reporting tool with no output schema, this description is exceptionally complete. It covers when to use, what to avoid, how the claim_token recovery works, rate limiting, cost, and team response expectations. The nested context parameter is documented in schema, and the description ties it to concrete tool/pack/vertical examples. The agent has everything needed to invoke correctly.

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

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

Schema coverage is 100% with detailed descriptions for all four parameters (type enum, context object, message, claim_token). The description adds beyond the schema by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})' and 'with no other arguments'), plus the connection-level caveat. This complements rather than repeats schema content, so above baseline.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates the feedback types (bug, feature/data_gap, praise), distinguishing this from sibling tools like ask_pipeworx or discover_tools. The scope limitation to 'tools served by this Pipeworx connection' further sharpens purpose.

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

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

Provides explicit when-to-use triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also states a clear exclusion: if the tool came from a different MCP server, file it there instead. This gives the agent decisive guidance for selecting this tool over alternatives.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds critical behavioral context: data source (CF analytics-engine), no PII, cached 5min-1h. This fully informs the agent about safety and freshness.

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 (two sentences plus a bullet list), front-loaded with the core function, and every sentence adds value. No redundancy or fluff.

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

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

For a single-optional-parameter tool with strong annotations, the description covers purpose, usage, parameter semantics, and behavioral traits completely. No output schema needed.

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

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

The description adds semantic guidance for the window parameter ('Shorter windows surface what's hot right now; longer windows show steady-state demand.') beyond the schema's enum description, though no new syntax is added.

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 returned data (top tools, top packs, total call volume) and the time windows. It distinguishes itself from siblings like discover_tools by focusing on trending usage rather than discovery.

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 (discovering hot data sources, confirming canonical tools, aligning use case with demand) and explains window selection. It lacks explicit when-not-to-use or alternative tool mentions, but provides sufficient guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive, open-world. The description adds significant behavioral details: the arbitrage computation logic, fill check using live CLOB depth, semantic anchor (Jaccard similarity), partition filter (placeholder fraction), response fields, and the condition for null arb signal. No contradiction with annotations.

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

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

The description is very detailed but somewhat verbose. It is well-structured with front-loaded purpose and uses bold mode names. However, some sections (e.g., the fill check explanation) could be more concise without losing clarity. It earns its length but could be trimmed.

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 (three modes, multiple checks, fill analysis) and no output schema, the description covers all necessary information: how to call with no args, event, or topic; response structure (opportunities array, partition_check fields); fill check and when to avoid trading; prerequisites (slugs, URLs); and a reference to polymarket_fill_risk 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 both parameters described in the input schema. The description adds extra context: for event, it gives examples of slugs and states that full URLs are accepted; for topic, it provides examples and explains the cross-event search behavior. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's core purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It names specific resources (Polymarket markets) and actions (scan, check, etc.) and distinguishes three modes (no args, event, topic) with clear functionality. This differentiates it from siblings like polymarket_edges or polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. It explains the benefit of cross-event mode and includes a fill check warning ('do not trade it' when realizable_edge_pp <= 0). However, it does not explicitly contrast with sibling tools for similar tasks.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructive action. The description adds numerous behavioral details: caching strategy, diagnostic output for empty segments, tradeable-edge knobs, and model-specific behavior (e.g., placeholder-slug filter, Fed note). 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 front-loaded with the purpose and is well-structured with clear sections for model families, response structure, and knobs. It is somewhat verbose but each sentence adds unique value; minor redundancy could be trimmed.

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, multiple models, no output schema), the description is remarkably complete. It explains the output structure (by_segment, fed_candidates, diagnostics), model details, and caching behavior, leaving little ambiguity 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%, and the description provides additional context for parameters (e.g., min_kelly explains skipping small opportunities, slippage_pp explains Polymarket fees). This adds value beyond the schema definitions.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with price. It specifies the resource (Polymarket markets), action (scan and return), and differentiates from siblings like polymarket_arbitrage by focusing on edge detection with proprietary data.

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 frames the tool for daily opportunity discovery ('what should I bet on today'), describes when to use it (agents discover opportunities), and includes notes on Fed bets. However, it does not explicitly compare to sibling tools or state when not to use it.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context: it explains that snapshots have gaps ('gaps mean nobody scanned that day'), describes the derived trend/decay calculations, and clarifies that decay numbers come from daily closes. No contradiction with annotations.

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

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

The description is a dense paragraph but contains no filler; every sentence adds value. It is front-loaded with the core purpose and then details output structure and limits. Could benefit from more structured formatting, but it's concise given the complexity.

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

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

With no output schema, the description fully covers the return structure: tracked[], expired[], snapshot_dates[], and explains derived fields (first_seen, trend, decay_pp_per_day). Also addresses data gaps and TTL limits, making it complete for effective tool usage.

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

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

Schema coverage is 100% for both parameters. The description adds practical context: default for days is 14 with max 30, default window is '1wk', and explains the snapshot family concept. It enhances understanding without being necessary for correctness.

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 provides a specific verb+resource combination: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence and decay, answering 'how long has this edge existed and is it shrinking?'

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

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

The description implicitly guides usage by contrasting fresh vs. old wide edges, and mentions LIMITS like the 60-day snapshot TTL. However, it does not explicitly state when not to use this tool or name direct alternatives, so it does not achieve a 5.

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

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

Annotations already indicate readOnlyHint=true, etc. The description adds critical behavioral details: walks the order book ladder, returns verdict (clean|degraded|cannot_fill), warns about partial basket fills converting arb to directional risk, and explains forced directional risk. This goes well beyond what annotations provide.

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

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

Description is well-organized with bold section headers for SINGLE-MARKET and BASKET, uses clear language, and every sentence provides essential information. It is front-loaded with the core purpose. No fluff or redundancy.

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

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

Despite no output schema, the description comprehensively lists all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, thin_legs, max_clean_notional_usd). It explains the edge check concept, covers risks like partial fills and directional exposure, and provides usage thresholds. Highly complete for a complex tool.

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

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

Although input schema has 100% description coverage, the description adds significant meaning: clarifies size_usd as 'max spend on buys, target proceeds on sells', explains side auto-detection from partition sum, and distinguishes market vs event in detail. This deepens the agent's understanding 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 it performs a realizable-vs-theoretical edge check against live order book depth, with explicit modes (single-market and basket) and expected returns. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by directing usage before acting on their signals.

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: before any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. It specifies required parameters ('REQUIRES one of market or event'), explains default behaviors for side and size_usd, and contrasts single-market vs basket modes.

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

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

The description goes beyond annotations (readOnlyHint, idempotentHint, etc.) by detailing behavioral traits such as the compatibility_warning conditions (matched_pairs=0 with skipped_cross_type>0 or skipped_cross_type=0 with both venues>5 legs) and temporal_alignment. No contradictions with annotations; it supplements them.

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

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

The description is well-structured with clear sections for purpose, modes, response, and safety fields, and it front-loads the primary purpose. While it is relatively long, every sentence contributes useful information; minor redundancy could be trimmed, but overall it is efficient and well-organized.

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

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

Given the tool's complexity (cross-venue spread, multiple parameters, no output schema), the description is comprehensive. It explains the spread calculation, safety fields (compatibility_warning, temporal_alignment, skipped counters), and even warns that pre-mapped topics may not yield tradeable spreads. It provides sufficient context for correct 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 the schema already documents parameters. The description adds value by explaining the behavior of the topic parameter (pre-mapped shortcuts) and how explicit tickers override, as well as the context of compatibility warnings. It provides meaningful context beyond schema descriptions.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific verb and resource. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons and mentions two modes: topic shortcuts and explicit tickers.

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

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

The description provides explicit guidance on when to use the tool, including two modes (topic vs explicit tickers) and warnings that pre-mapped topics often return compatibility_warnings, indicating that spreads may not be tradeable. It also explains when to use alternatives implicitly by contrasting modes.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds scoping detail and the behavior of listing all keys when key is omitted. No contradictions.

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

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

Three sentences, zero waste. Front-loaded with core purpose, then usage context, then technical detail. Every sentence adds value.

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

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

Given low complexity (one optional parameter) and rich annotations, description adequately covers retrieval behavior, scope, and relationship to sister tools. No gaps.

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

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

Only one parameter, fully described in schema. Description restates schema meaning but does not add new details about format or constraints. Baseline 3 applies due to high schema coverage.

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

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

Clearly states retrieval or listing of saved values. Verb 'retrieve' and noun 'key' specify exact action and resource. Distinguishes from sister tools remember and forget by mentioning pairing.

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

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

Describes when to use (look up stored context) and scope (per identifier). Doesn't explicitly state when not to use, but context is clear enough for an agent.

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

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

Annotations indicate readOnly, idempotent, and non-destructive. The description adds behavioral context: mark_read mutates state (flags events as read), persistence of feed, and that each event carries specific fields. No contradiction with annotations; enhances 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?

The description is concise with each sentence contributing unique information. It front-loads the main purpose and filtering options. Could be slightly more compact, but overall efficient and 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?

No output schema, but description fully explains return fields (source, citation_uri, payload). Covers all parameters, use cases (polling, filtering), and provides alternative access method. Comprehensive for a tool with complex behavior.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining each parameter's purpose with examples (type filter like 'sec_8k', mark_read effect), going beyond schema descriptions. It clarifies behavior of unread_only and since, making parameter semantics richer.

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

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

The description clearly states the tool pulls fired events from subscription feed and returns recent alerts. It uses specific verbs ('pull', 'returns') and resources ('events', 'alerts'), and distinguishes from sibling tools like list_subscriptions by focusing on alert content.

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 filtering by type and since, use of mark_read, and mentions polling suitability. It also provides an alternative HTTP endpoint for scripts/dashboards. While it doesn't explicitly state when not to use, the guidance is clear enough for effective 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 read-only, idempotent, non-destructive behavior. The description adds specific details: fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail, and return structure. This goes beyond annotations, though rate limits or error handling are not detailed.

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

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

The description is a single dense paragraph that front-loads the purpose and examples. Every sentence adds value, but it could be slightly more structured with bullet points for readability. Not verbose.

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

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

Given no output schema, the description compensates by describing the return structure. It covers source behaviors and sibling differentiation. However, it lacks details on pagination or comprehensive error handling.

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 with examples (ISO dates, relative shorthands, typical monitoring value) and clarifies that `value` accepts ticker or CIK. This enhances 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 the tool provides a change feed for a company over a time window, combining SEC, GDELT/GNews, and USPTO sources. It explicitly distinguishes from the sibling tool `entity_profile` by specifying when to use each.

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 example queries and explicitly advises using `entity_profile` for static profiles. However, it does not provide a comprehensive list of when not to use this tool, though the examples imply appropriate use cases.

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

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

Adds behavioral details beyond annotations (persistent for authenticated users, 24-hour for anonymous) 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?

Four concise, front-loaded sentences with 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?

Complete for a write tool with good annotations and full schema; no output schema needed as storage is side effect.

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 value with key-value pair context, scoping by identifier, and 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?

Clearly states the tool 'saves data to reuse later' with specific examples like ticker, address, preference, distinguishing it from siblings recall and forget.

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and pairs with recall/forget, providing clear usage context.

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

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

Annotations declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: graceful degradation when external sources are unavailable, explicit `unresolved` field, source labeling for each identifier, internal cascading through several lookup endpoints, and coverage for non-US issuers. No contradiction.

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

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

The description is long but front-loaded with user-intent examples and structured with clear sections for supported types, fallback behavior, and internal operation. Each sentence adds value, though the density could be intimidating.

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

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

With no output schema, the description fully compensates by disclosing return semantics (source-labelled identifiers, unresolved section, ownership/children), operational behavior (graceful degradation, cascading lookups), and pitfalls like non-US issuers. It covers both entity types thoroughly and leaves little ambiguity about what the tool returns.

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

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

Schema coverage is 100%, but description adds significant meaning beyond the property descriptions: accepted input formats (ticker, CIK, ISIN, name), concrete examples (AAPL, 0000320193), and the brand/generic distinction for drugs. It also explains how an ISIN resolves to the legal entity, which is non-obvious from the schema alone.

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

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

Description uses specific verbs: 'resolve a user-spoken NAME to canonical/official identifiers' and enumerates supported types (company, drug). It clearly differentiates itself as the identifier-resolution entry point that other tools depend on, distinguishing it from siblings like entity_profile or compare_entities.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID' and provides numerous natural-language query examples. It does not explicitly name what to use when you already have an identifier, but the guidance is strong and contextually 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, idempotentHint, etc. The description adds value by explaining the probing process, ranking logic, and output fields (score, confidence, signal density). No negative behaviors are hidden.

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

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

Two sentences: first covers purpose and process, second covers use case and output. No redundancy, 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?

With no output schema, the description adequately explains return values (ranked list with score, confidence, signal density). It also covers input constraints (2-8 entities, first is subject) and model options. Sufficient for agent understanding.

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 important semantics: the first entity is treated as the 'subject' for narrative, and it clarifies model options including the need for an API key with 'anthropic'. This goes beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. It includes a concrete example and differentiates from sibling tools like ai_visibility_check (single check) and compare_entities (generic comparison).

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

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

The description provides clear context for use ('useful for competitive AI-marketing audits') and gives an illustrative question. However, it does not explicitly mention when not to use it or suggest alternatives like ai_visibility_check for single entities.

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

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

Discloses important behaviors beyond annotations: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. This is valuable context for the agent. Annotations already indicate readOnly and idempotent, but description adds timing and failure mode details.

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

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

The description is longer than typical but every sentence adds substantive information. It is front-loaded with purpose and usage, but could be slightly more structured. Still, it earns its length.

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

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

Despite having no output schema, the description explains the return structure in detail (summary block fields, per-advisory detail, links, alternative versions). This is complete and well-suited for an agent to understand the tool's output.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description adds value by mentioning scoped packages are accepted and version defaults to latest, but this is marginal. Baseline 3 is appropriate.

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

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

The description clearly states what the tool does: a composite check for evaluating npm packages, combining deps.dev and bundlephobia data. It uses a specific verb (scan) and resource (dependency) and distinguishes from siblings by being a one-call composite that covers multiple aspects.

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

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

Explicitly states when to use the tool: when an agent asks about safety, popularity, or size of an npm package. It also provides an alternative for other ecosystems (PyPI/Maven/Cargo/Go fall under deps.dev directly), guiding the agent on tool selection.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds specific behavioral details: BGE-base-en embeddings, cosine similarity over 500-char windows, 200K char cap with truncation flag, and that every passage carries an offset for verification.

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

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

Front-loaded with purpose, then usage, then technical details. Every sentence is informative with no fluff; appropriately sized for the complexity of a semantic search tool.

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

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

Despite no output schema, the description explains return values (top-N passages with character offsets and similarity scores). Also covers max input size, embedding details, and pairing with another tool, making it self-contained for correct agent usage.

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

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

Schema coverage is 100%, but description adds value by providing examples for 'query', default value and range for 'limit' (1-20, default 5), and clarifications like 'max ~200K chars' for 'text'.

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 semantic search inside a fetched record, with specific examples (SEC 10-K, article, long tool result) and distinguishes from sibling tool ask_pipeworx_grounded by explaining their pairing.

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 ('record too big to cram into the prompt') and explains benefits (saves context, returns relevant passages with offsets). Describes pairing with ask_pipeworx_grounded, providing clear guidance on 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?

Adds significant behavior beyond annotations: subscription persistence, OAuth requirement, SMS daily cap, webhook signing secret and auto-disable after failures. Contradicts no annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false are consistent).

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

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

The description is dense but well-organized, front-loading the core purpose. Every sentence adds value, though the enumeration of types could be more concise. Still efficiently communicates complex behavior.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description fully explains all types, delivery options, preconditions, and edge cases (SMS verification, webhook secret one-time return, auto-disable). No gaps identified.

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

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

Schema coverage is 100%, but description goes far beyond by providing type-specific parameter examples (e.g., items codes for sec_8k, topic for polymarket_edge), and extended delivery channel details including webhook signature verification and error states.

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: 'Create a proactive monitoring subscription to a live-data event stream' with verb 'create' and resource 'subscription'. It distinguishes from siblings like 'list_subscriptions' and 'unsubscribe' by its proactive monitoring nature.

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 context: requires Pipeworx OAuth account (non-anonymous), lists supported subscription types with examples, and details delivery channels. Lacks direct comparison to sibling tools but includes constraints like SMS cap and webhook auto-disable.

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 nature. The description adds context about returning example questions with exact tool and argument shapes drawn from a live catalog, which goes beyond the annotations. No contradictions.

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

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

The description is informative but somewhat lengthy. It front-loads common question variants, which is good, but the list of categories could be trimmed for brevity 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 the tool's role as an onboarding meta-tool, the description covers its main use cases, return format (categorized examples with tool+argument shapes), and context for use. No output schema is needed. It is sufficiently complete for an agent to understand when and how to invoke it.

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

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

Schema coverage is 100% for the single optional parameter. The description adds meaning by listing example topic values and explaining how the parameter focuses the output, thus going beyond the schema's description.

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

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

The description clearly states the tool's purpose: returning category-bucketed example questions for onboarding. It specifies the verb 'returns' and the resource, and distinguishes it from sibling tools like ask_pipeworx by positioning it as the entry point for new users.

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

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

The description explicitly advises using this tool first when the agent does not know what Pipeworx can do. It also explains when to pass the optional topic parameter versus omitting it for a full spread. However, it does not provide explicit negative guidance (when not to use), though the positive guidance is strong.

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

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

Beyond annotations, the description reveals important behavioral traits: ownership enforcement, deactivation instead of deletion, and preservation of historical data. This provides significant value over annotations alone. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

Two concise sentences, front-loaded with the primary action. Every sentence adds essential information without redundancy. Highly 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 single-parameter tool with no output schema, the description covers purpose, behavior, ownership, and outcome completely. It fits well with sibling tools like 'subscribe' and 'list_subscriptions'.

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 'id' parameter. The tool description does not add further semantic detail about the parameter beyond what the schema already provides. Thus, it meets the baseline for high coverage.

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

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

The description clearly states the action ('cancel a subscription'), resource (by id), and distinguishes it from deletion ('deactivated, not deleted'). It also specifies ownership enforcement, making the tool's purpose unambiguous and distinct from siblings 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?

The description provides clear context: ownership is enforced, so only own subscriptions can be canceled. It explains the outcome (deactivation vs. deletion). However, it does not explicitly state when to use this tool versus alternatives (e.g., if a delete tool existed), though the context is sufficient for correct 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 provide safety hints (readOnly, idempotent, non-destructive), and the description adds crucial semantic distinctions: the meaning of could_not_verify vs unsupported, that could_not_verify is not evidence, and the two-path execution strategy with exact percent-delta math. This exceeds the minimal bar for annotation-complementing disclosure.

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

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

The description is dense but well-organized: trigger phrases first, then scope, then internal behavior, then return values, then edge-case warnings, then efficiency note. It is appropriately sized for a tool with this complexity, with no redundant sentences.

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

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

The tool has two routing paths, multiple verdicts, and no output schema. The description covers inputs, when to use, both execution paths, the full verdict set, citation behavior, and the critical semantic difference between two verdicts, plus a performance note. It is comprehensive for a tool this complex.

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

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

The input schema already documents both parameters fully (100% coverage), so the baseline is 3. The description adds general context about routing and tolerance math but doesn't add specific parameter-level semantics beyond what the schema provides.

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

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

The description names a specific verb+resource: natural-language claim verification against authoritative sources. It includes trigger phrases and distinguishes the SEC EDGAR fast path for company financial claims versus the grounded pipeline for all other facts, clearly separating it from general Q&A siblings.

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?

States 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the automatic routing between two pipelines. It does not explicitly name alternative tools to avoid, but the scope is clear enough to prevent confusion with ask_pipeworx or deep_research.

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