Conspiracy Theory

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false, consistent with a safe read operation. The description adds valuable behavioral details: default model cost (free), Anthropic requires BYO key, and return structure includes per-model and combined views.

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

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

The description is three sentences, front-loading the main action and covering purpose, usage, and output. Every sentence adds value 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 4 parameters, no output schema, but rich annotations, the description covers input, usage, output shape, and cost implications. It is complete for an agent to understand and invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining default model, when _apiKey is needed, and that context is for disambiguation. This provides practical parameter context.

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

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

The description clearly states the verb 'probe' and the resource 'LLMs', specifying that it scores visibility (0-100) per model. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on probing multiple LLMs and providing a quantitative score.

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

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

The description lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to pass `_apiKey` and that the default model is free. However, it does not explicitly compare to similar 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description reveals the tool routes queries to one of 4,774 tools, fills arguments, returns structured answers with pipeworx:// citation URIs. This adds significant behavioral context not present in annotations.

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

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

Efficiently front-loaded with 'PREFER OVER WEB SEARCH'. Every sentence adds value: usage guidance, source types, examples, tiered recommendations. No wasted words despite length.

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

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

Given the tool's broad scope and no output schema, the description adequately covers purpose, behavior, usage context, and alternatives. It explains the answer format (structured with citations) and gives concrete examples, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with all parameters described. The description adds value by providing concrete examples of questions and clarifying the type of input expected. It does not repeat schema details but the examples enhance semantic understanding.

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

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

The description clearly states the tool's function: answering questions about current or historical structured data from verified sources, with specific examples. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by listing explicit use cases and guidance.

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 and when-not-to-use guidance. States 'PREFER OVER WEB SEARCH', advises to start here for most questions, and specifies step-up alternatives like ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad queries. Also addresses breaking news routing.

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, etc.), the description details the refusal mechanism, including the exact refusal reasons and that the tool uses only the tool result. It also warns about the extra cost. No contradiction with annotations.

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

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

The description is front-loaded with the key purpose, and each sentence adds value. Slightly verbose but well-structured and informative. Could be trimmed marginally, but overall concise.

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

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

Given the tool's complexity (routing, extraction, refusal), the description covers all aspects: behavior, return format, refusal reasons, cost trade-off, and use cases. No output schema, but return structure is explained. Complete context for high-stakes queries.

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

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

Input schema has 100% description coverage with aliases explained. The description does not add new parameter semantics beyond stating that the question is in natural language. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explains the process (routing, fetching, extracting) and distinguishes itself from sibling 'ask_pipeworx' by noting the extra LLM call and the specific use case of avoiding invention.

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

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

Explicitly advises when to use: 'Use whenever an answer will be quoted, cited, or acted on...' with examples of high-stakes domains. It also states when to prefer the alternative: 'prefer ask_pipeworx for casual lookups.' Provides clear guidance 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?

The description goes far beyond the annotations by detailing safe behaviors: low-confidence matches short-circuit with a status, closed markets return 'market_closed_or_inactive', wide-spread markets carry a liquidity warning, and resolution-rule risk is explained. It also covers the resolver contract, parent event extractor, and news fallback mechanisms, providing deep 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 long but well-structured, with front-loaded purpose and logical sections for fan-out examples, response shapes, and safety mechanisms. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

Despite lacking an output schema, the description comprehensively covers the response shape (result.market, result.analysis, result.evidence), resolver confidence, parent event extraction, news fields, and safety short-circuits. It addresses edge cases like closed markets and low-confidence matches, making it highly complete for a complex tool.

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

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

The input schema has 100% description coverage, so the schema already documents all three parameters. The description adds little extra meaning beyond what the schema provides (e.g., examples for 'market' input), and the 'depth' and 'include_raw' are clearly described in the schema. A baseline of 3 is appropriate.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, specifying input types (slug, URL, question text) and outlining the process (resolving, classifying, fanning out). It distinguishes itself from siblings like 'polymarket_edges' by focusing on a single bet's evidence packet, making its purpose unambiguous.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and gives examples of fan-out for various bet types. However, it does not directly state when NOT to use this tool or point to specific alternatives, which slightly reduces the score.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), metrics returned (revenue, net income, cash, debt; adverse events, approval counts, trial counts), sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

Although somewhat lengthy, every sentence adds value—trigger phrases, behavior, data sources, sorting, return format, efficiency note. The description is well-structured and front-loaded.

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

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

For a tool with 2 parameters, no output schema, and safety annotations, the description covers purpose, when to use, what data is pulled, how results are sorted, and return format. No obvious gaps.

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

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

Schema already describes parameters with 100% coverage. The description adds meaning by specifying exact metrics for each type (company vs drug) and giving formatting examples (tickers/CIKs vs drug names), going well beyond schema.

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

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

The description clearly states the tool provides side-by-side comparison of 2-5 companies or drugs, lists trigger phrases like 'Compare X and Y', and distinguishes from sibling tools like entity_profile by advocating preference over sequential single-pack 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', provides example queries, and notes it replaces 8-15 sequential lookups, making usage context very 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 mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds behavioral context by specifying that it generates fictional content, which aligns with annotations. No contradictions or missing disclosures.

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?

A single sentence efficiently conveys the core functionality, modes, and controls. No extraneous information; every phrase adds value.

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

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

Given the tool's complexity (three modes with conditional parameters), the description covers all key aspects. The presence of an output schema (not shown) reduces the need for return value details.

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 57%, and the description adds meaningful context for each mode, clarifying how parameters like thing_one, thing_two, event, and prompt are used. The enums are explained indirectly through mode examples.

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

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

The description clearly states it generates a conspiracy theory with three distinct modes ('connect', 'investigate', 'complete') and adjustable depth/confidence, distinguishing it from the listed sibling tools which have unrelated purposes.

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

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

It explains each mode's use case (linking things, exploring events, extending prompts) and provides parameter guidance. However, it does not explicitly state when not to use the tool or suggest alternatives, though the sibling list indicates disparate functions.

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, openWorld), the description discloses account requirements, paid plan for 'thorough' depth, expected timing (15-60s), output structure (findings packet with evidence, gaps, citations), and that it never invents answers. No contradiction with annotations.

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

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

The description is lengthy but each sentence provides essential information: account requirement, alternative tool, core capability, usage advice, timing, output format. It is front-loaded with critical details. Minor redundancy could be trimmed, but overall efficient 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?

With only 2 parameters and no output schema, the description fully compensates by detailing the output format (verbatim evidence, confidence, source, fetched_at, citations, gaps), use cases, timing, and constraints. It is comprehensive for a complex research tool.

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

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

Schema coverage is 100%, and the description adds meaningful context: it explains the depth enum values (quick=3, standard=5, thorough=8) and the paid requirement for 'thorough'. It also clarifies that the question parameter accepts natural language and broad/multi-part queries.

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 for grounded multi-source research across structured data sources, decomposing into facets. It distinguishes itself from sibling tools like ask_pipeworx by emphasizing it is not open-web search and is best for broad/multi-part questions.

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

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

Explicitly provides when to use (broad/multi-part questions over structured data), when not to use (single lookups, breaking news), and alternatives (ask_pipeworx for simple queries, live news). Also notes account requirements and depth restrictions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that results are 'ready to call directly, no second schema lookup needed,' which is valuable behavioral context beyond the annotations. It does not contradict annotations.

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

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

The description is somewhat lengthy but well-structured: purpose, usage, and return format are front-loaded. Every sentence adds value, though some redundancy exists (aliases repeated in schema and description).

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

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

Given no output schema, the description fully explains what is returned (names, descriptions, full input schemas with curated examples). It provides enough context for an AI agent to understand the tool's role in the discovery workflow.

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 each parameter is described clearly. The description adds context about the query parameter (e.g., natural language description) and mentions max limit, but does not significantly extend the schema's own descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It includes numerous specific examples of data domains (SEC filings, FDA drugs, etc.) and explains what the tool returns (top-N relevant tools with full schemas). It implicitly distinguishes itself from siblings by being the meta-tool for 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 guides when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It provides context for usage but does not explicitly name alternative tools for specific 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 declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint false, indicating safe, non-modifying behavior. The description adds valuable context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields with formatting, notes that patents API sunset in May 2025 and soft-fails, and explains input requirements. 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 fairly long but each sentence provides essential information—example queries, sources, output details, limitations, and usage guidance. It is front-loaded with the most critical information. While packed, it remains readable; slight trimming could make it more concise, but it is not overly verbose.

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

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

Given the tool's complexity (multi-source aggregation, no output schema, 2 parameters with 100% schema coverage), the description covers all necessary aspects: input formats, sources, returned fields (including field format), failure modes (patents soft-fail), and when to use another tool. It leaves no critical gaps for the agent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning: 'type' only supports 'company' today (person/place coming soon), 'value' accepts ticker or zero-padded CIK, and explicitly states names are not supported. This goes well beyond the schema alone.

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

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

The description opens with clear example queries and explicitly states it returns a 'full cross-source profile of a US public company'. It lists specific data sources and output fields, making the purpose unmistakable. This strong verb+resource combination distinguishes it from sibling tools like 'resolve_entity', which is for name resolution.

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

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

The description explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. It also states 'names not supported — use resolve_entity first if you only have a name', providing clear when-to-use and when-not-to-use guidance with an alternative sibling tool.

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

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

Annotations already indicate destructive and idempotent behavior. Description adds context about deleting previously stored memories and clearing sensitive data, enhancing understanding beyond annotations without contradiction.

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

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

Three sentences, front-loaded with purpose, each sentence adds value. Extremely concise 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?

For a simple deletion tool with one parameter and no output schema, the description fully covers what, when, and how to use, along with sibling relationships. No gaps given the tool's simplicity and rich 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 covers the single parameter 'key' with description 'Memory key to delete' (100% coverage). Description mentions 'by key' but adds no extra semantics like key format or origin, making it adequate but not exceptional.

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 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings by naming 'remember' and 'recall' as complementary operations, providing clear differentiation.

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

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

Explicitly lists when to use: when context is stale, task is done, or clearing sensitive data. Also suggests pairing with remember and recall, offering clear context and alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds that it fetches the page and extracts title/description/key links, providing insight into the background process, which is useful beyond the annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, then process, then use cases. Every sentence adds value, 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 no output schema, the description covers output format ('standard llms.txt markdown format', 'single text blob') and explains what the tool does, which is sufficient for an agent to understand and 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?

Both parameters are fully described in the schema (100% coverage). The description adds extra context: 'url' is the full URL to summarize, and 'max_links' includes default (25) and maximum (50) values, which are not in the schema but enhance understanding.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the exact actions (fetch, extract, emit). It is distinct from sibling tools like 'scan_competitor_ai_presence' which focus on analysis rather than generation.

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

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

The description lists explicit use cases (getting a client's site indexed, drafting for own project, auditing competitors) but does not provide conditions when not to use or contrast with specific alternatives among the 27 siblings.

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

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

Adds context beyond annotations: scopes listing to caller, specifies return fields, explains parameter for inactive subscriptions. All annotations (readOnly, idempotent, non-destructive) are consistent and reinforced.

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: purpose+returns, usage guidance. No unnecessary words, front-loaded with key action.

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

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

Simple tool with one optional parameter, no output schema needed. Description covers purpose, usage, and parameter effect. Sufficient 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% and the description does not add semantic meaning beyond the schema's parameter description. Baseline score of 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' with verb+resource+scope. It distinguishes from sibling tools (subscribe, unsubscribe) by focusing on listing and provides return fields.

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

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

Explicitly advises use 'before adding more or to find an id to cancel', providing clear when-to-use guidance and contrasting with subscription management siblings.

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

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

Annotations are all false, but description adds significant behavioral context: rate-limited, free, doesn't count against quota, team reads daily, signal affects roadmap. No contradictions with annotations.

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

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

The description is concise (around 5 sentences), front-loaded with purpose, and each sentence provides unique value. No redundancy. Perfectly structured.

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

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

For a feedback tool with no output schema, the description covers purpose, usage, and parameters well. However, it does not mention the expected response (e.g., acknowledgment or error). Minor gap, but overall complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by elaborating on the enum values (bug means something broke, feature means new tool, etc.), the optional context object with examples, and the message constraints (be specific, 1-2 sentences, 2000 chars max). 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's purpose: sending feedback (broken, missing, something to exist). It immediately defines types (bug, feature/data_gap, praise) and distinguishes from sibling tools by being a dedicated feedback channel. The verb 'Tell' and resource 'Pipeworx team' are specific.

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 describes when to use each feedback type (bug for wrong data, feature for missing tool, etc.) and what not to do (don't paste end-user prompt). Also includes rate limit (5/identifier/day) and that it's free. No need for when-not beyond this clarity.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds concrete details: self-aggregating from CF analytics, no PII, cached 5min-1h. No contradictions.

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

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

Concise (3-4 sentences), front-loaded with main output, then use cases and additional context. Every sentence adds value; no 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?

Good overall; explains return fields, use cases, caching, and privacy. Lacks explicit output schema but sufficient for a simple trending tool. Minor gap: doesn't detail format of top tools/packs.

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 enum and description for 'window'. Description adds valuable nuance: shorter windows for hot trends, longer for steady-state demand.

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

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

Description clearly states the tool returns top tools, packs, and call volume over specified windows. It distinguishes 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?

Provides three explicit use cases (discovering hot sources, confirming canonical choice, aligning use case). While it doesn't explicitly list when not to use it, the context is clear and helpful.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses internal algorithms (monotonicity checks, partition_sum, semantic anchor, partition filter, fill check) and constraints (Jaccard similarity >= 0.30, placeholder filtering, realizable edge <= 0 indicates no trade). This provides rich behavioral context without contradicting any annotation.

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 sections and front-loaded summary, but it is somewhat verbose. Every sentence adds value, though some details could be more concise without loss of clarity.

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

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

Despite no output schema, the description fully explains the return fields (opportunities[], partition_check with subfields). It covers edge cases (skipped_low_similarity, placeholders_filtered) and integrates with sibling tools. Given its complexity and reliance on dynamic data, the description is remarkably complete.

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

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

Although schema coverage is 100%, the description adds significant meaning beyond the schema: it explains the difference between event and topic modes, provides example values, and describes the internal logic (e.g., cross-event scanning catches patterns missed by single-event). This exceeds the baseline of 3 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 tool finds arbitrage opportunities on Polymarket via specific methods (monotonicity violations + partition-sum checks). It distinguishes three modes (no args, event, topic) and explains what each does, making it easy to differentiate from sibling tools 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 explicitly tells when to use each mode: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It provides examples of inputs (e.g., event slugs, seed questions) and warns against trading when the fill check shows no realizable edge. It also references polymarket_fill_risk for custom sizing, guiding the agent to 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?

Description adds extensive behavioral context beyond annotations: caching (1h at KV level), output structure (by_segment, diagnostics), and explanations of model families and edge computation. No contradiction with annotations.

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

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

Description is long but well-structured with sections for model families, response segments, and knobs. Front-loaded with purpose. Technical details are relevant but could be slightly more concise.

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

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

Despite no output schema, description comprehensively explains all fields in the response (by_segment, edge_pp_net, kelly_fraction, diagnostics). Covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaningful context for parameters like min_partition_leg_kelly (explains why min_kelly doesn't filter partition arbs) and min_liquidity (thin-book opportunities). Adds value beyond schema.

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

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

Description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. Distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx disagreements.

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 'Built for what should I bet on today' and explains knobs like min_liquidity and max_spread_pp for filtering tradeable edges. Does not compare with siblings but provides usage context and notes Fed bets are excluded from ranking.

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 context beyond annotations: snapshot gaps on cache miss, 60-day TTL, decay computed from daily closes not intraday. Annotations already indicate read-only, idempotent, non-destructive, which align.

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

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

Well-structured: starts with key question, then parameters, response breakdown, and limits. Though lengthy, each part serves a purpose and is front-loaded with the core insight.

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?

Thoroughly explains the complex output (tracked, expired, snapshot_dates) with clear definitions. Without an output schema, the description fully compensates. Covers limits and caveats (gaps, TTL).

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

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

Schema covers 100% of parameters. Description adds details like clamp range for 'days' and valid options for 'window', plus explains how parameters affect the response (e.g., snapshot family).

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

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

Clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge age and shrinkage. Distinguishes from 'polymarket_edges' by focusing on historical tracking rather than current edges.

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

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

Gives clear usage context by contrasting fresh vs. old edges. Does not explicitly mention when not to use or alternatives, but the purpose implies differentiation from sibling 'polymarket_edges'.

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, idempotentHint, destructiveHint), the description details behavioral traits: 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict.' It also covers forced_directional_risk and thin_legs, adding significant context for safe 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 well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). Despite length, every sentence is informative, using bullet-point-like formatting in prose. It balances detail and conciseness 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 explains return fields for both modes, including verdicts and risk indicators. It covers error conditions (thin books, partial fills) and practical implications, making it complete for agent decision-making.

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

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

With 100% schema description coverage, the description adds substantial meaning: default side behavior, size_usd interpretation differences between modes, and the exclusivity of market vs. event. It explains the default for size_usd and its clamp, providing value beyond the schema.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and lists specific return fields, making it highly specific and differentiated from sibling tools like polymarket_arbitrage.

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

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

The description explicitly directs when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale, such as partial basket fills converting arb into unhedged directional positions, and provides conditions for market vs. event parameters.

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior. The description adds significant detail about response structure, safety fields (compatibility_warning, temporal_alignment, skipped types), and when spreads are invalid, providing transparency beyond the annotations.

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

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

The description is lengthy but well-structured with clear sections for modes, response, and safety fields. Every sentence adds value, though it could be slightly more concise.

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

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

Given no output schema, the description thoroughly explains response fields and safety conditions, covering compatibility_warning triggers, temporal alignment, and skipped comparisons, ensuring an agent can set expectations completely.

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

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

Schema has 100% description coverage with examples and descriptions for all parameters. The description reiterates modes but adds limited new meaning beyond the schema, justifying a baseline of 3.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, distinguishing it from sibling tools like polymarket_arbitrage.

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

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

Explicitly describes two modes (topic and explicit), explains when spreads are meaningful vs not via compatibility_warning, and warns that most pre-mapped topics are not tradeable, guiding appropriate usage.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: retrieval is scoped to an identifier, and it can list all keys. It does not contradict annotations. The description is clear but does not elaborate on any other behavioral traits (e.g., concurrency, staleness).

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 (3 sentences), front-loaded with the primary action, and includes essential details about listing keys, scoping, and pairing. Every sentence adds value without 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 (one optional parameter, no output schema), the description fully covers its functionality: retrieval vs. listing, scoping, and relationship to sibling tools. No obvious gaps remain.

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

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

With 100% schema description coverage, the baseline is 3. The description adds significant value by explaining that omitting the 'key' parameter returns a list of all saved keys, and that the key is optional. This clarifies the parameter's behavior beyond the schema's type and description.

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

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

The description explicitly states the tool retrieves values saved via 'remember' and lists all keys when the key argument is omitted. It distinguishes from sibling tools 'remember' and 'forget' by specifying its action.

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

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

The description provides clear usage context: 'to look up context the agent stored earlier' and mentions pairing with 'remember' and 'forget'. It explains that omitting the key lists all keys, and notes scoping to an identifier. However, it does not explicitly state when not to use it or list alternative tools beyond siblings.

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

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

Adds value beyond annotations by describing mark_read behavior and feed availability, with no contradictions to the readOnly, idempotent, and non-destructive hints.

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

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

Three sentences, front-loaded with purpose, efficient and informative without waste.

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

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

Despite no output schema, the description explains returned fields and behavior comprehensively, making it complete for a polling/feed tool.

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

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

Schema coverage is 100%, and the description elaborates on parameters like since (ISO timestamp), mark_read (affects next call), and provides an example for type filter.

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

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

The description clearly states 'Pull fired events from your subscription feed' with specific details on returned fields and filtering options, distinguishing it from sibling tools.

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

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

Provides usage context (filtering, polling, alternative endpoint) but does not explicitly state when not to use this tool or compare to siblings.

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

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

Discloses fan-out to multiple sources, fallback behavior (GDELT→GNews), soft-fail for USPTO with reason, and return format including citation URIs. Annotations (readOnlyHint, idempotentHint) are consistent and description adds context beyond 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?

Description is well-structured with front-loaded purpose and examples, but slightly verbose. Every sentence adds value, though some could be tightened.

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 adequately explains return structure (changes[] grouped by source + total_changes + citation URIs). Given complexity (multiple sources, fallback, date parsing), description is complete.

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

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

Schema coverage is 100%, but description adds meaning: explains that 'since' accepts ISO date or relative shorthand with examples, 'value' can be ticker or CIK, and 'type' only supports 'company'.

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

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

The description uses specific verbs and resources ('change feed for a company', 'fans out to SEC EDGAR, GDELT→GNews fallback, USPTO') and explicitly distinguishes from the sibling tool 'entity_profile' which provides a static profile.

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

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

Provides explicit usage examples ('What's new with X', 'latest on Y') and clear alternatives ('Use entity_profile instead when you want the static profile').

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 idempotentHint=true, destructiveHint=false. Description adds context about key-value storage, scoping by identifier, and retention periods. No contradiction with annotations. Could optionally mention whether values can be overwritten or if there is a size limit, but given the simplicity, this is sufficient.

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

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

Single paragraph with clear flow: purpose → when to use → technical details (scope, persistence) → sibling tools. Every sentence contributes unique information; no redundancy or filler.

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

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

For a simple key-value tool with 2 params and no output schema, the description fully covers functionality, usage context, data retention, and tool relationships. Nothing missing 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 covers 100% of parameters with descriptions. The description's examples (e.g., 'subject_property') add minimal value beyond schema's 'Memory key' and 'Value to store'. Baseline 3 is correct; no extra parameter guidance provided.

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 for reuse across conversations/sessions, provides concrete examples (ticker, address, preference), and distinguishes from recall and forget. The verb 'Save' combined with the resource scope ('across this conversation or across sessions') is specific and unambiguous.

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

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

Explicitly states when to use ('discover something worth carrying forward') and what to avoid (re-lookup). Mentions pairing with recall and forget for complementary operations. Also clarifies persistence differences between authenticated (permanent) and anonymous (24h) sessions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe, read-only operation. The description adds valuable detail: each call cascades through several lookup endpoints, auto-disambiguation for company, and citation URIs returned. No contradictions with annotations.

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

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

The description is relatively long but well-structured: starts with example queries, then core purpose, then usage guidance, then detailed type descriptions. Every sentence adds value, though some redundancy could be trimmed (e.g., repeating 'supported types'). Still, it's efficient for the information density.

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

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

Given two entity types with different lookup behaviors and return fields, the description covers all necessary context. It explains input variations, output fields (ticker, CIK, RxCUI, etc.), and citation URIs. No output schema exists, but the description compensates by detailing return values. Complete for a resolution tool.

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

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

Schema has 100% description coverage, but the description still adds significant value by providing concrete examples for both parameters: for 'type' it lists the two values; for 'value' it gives specific input formats like ticker 'AAPL', CIK '0000320193', or drug names 'ozempic'. This makes the schema more actionable.

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

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

The description starts with concrete example queries ('What's the ticker for…'), then clearly states the tool's purpose: resolve a user-spoken name to canonical identifier. It distinguishes itself from sibling tools by saying 'Use FIRST whenever you have a name but need an ID.' The supported types and what they return are explicitly listed, making the purpose unmistakable.

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

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

The description provides strong guidance: 'Use FIRST whenever you have a name but need an ID.' It explains that the tool replaces 2-3 manual lookups, giving context for when to prefer it. However, it does not explicitly mention when not to use it or compare to specific alternatives like entity_profile, which could further clarify boundaries.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, which assures safe, non-destructive behavior. The description adds that it probes each entity with ai_visibility_check and ranks by score, surfacing most/least recognized entities. 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 four sentences, front-loaded with the core action, and every sentence adds value without redundancy. It is well-structured and concise.

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

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

Despite no output schema, the description explicitly states the return format (ranked list with score, confidence, signal density per entity). It fully explains the tool's behavior for its complexity and parameter set, making it complete for 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 description coverage is 100%, so all parameters are already documented. The description adds context about the probing process but does not introduce new parameter 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 clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check internally and ranking results. It distinguishes from ai_visibility_check (single entity) 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?

Explicitly states usefulness for competitive AI-marketing audits and provides an illustrative question. While it doesn't explicitly list when not to use or alternatives, the context is clear and sufficient for an agent to decide.

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

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

Annotations already indicate safe read-only operation. The description adds crucial behavioral details: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, and sources_failed will list timeouts. 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 moderately sized but front-loaded with the core purpose. It wastes no words and includes all necessary context, though it could be slightly tighter. Still clear and effective.

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

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

Despite lacking an output schema, the description comprehensively lists all return fields (summary block, advisory details, links, alternative versions) and handles edge cases like partial failures and version defaults. This fully compensates for the missing output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining scoped packages are accepted and defaulting to latest version if omitted, which goes beyond the schema's parameter descriptions.

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

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

The description clearly states it's a composite check for npm packages, combining deps.dev and bundlephobia. It specifies the verb 'scan' and the resource 'npm package dependency', and distinguishes itself from siblings by being the only tool that performs this combined analysis.

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

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

Explicitly says 'Use whenever an agent asks is X safe / popular / small' and notes the NPM-only scope, mentioning that other ecosystems are handled by deps.dev:version directly. Provides clear when-to-use and when-not.

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 safety hints (readOnlyHint, etc.). The description adds technical details beyond annotations: embedding model (BGE-base-en), chunking (500-char overlapping windows), length cap (200K chars with truncation flag), and return items (character offsets, similarity scores). 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?

Five well-structured sentences, front-loaded with main purpose, no wasted words. Each sentence adds value (purpose, usage, pairing, technical details).

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

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

Despite no output schema, the description explains return values (passages with offsets and similarity scores), usage scenario, technical constraints, and pairing with another tool. Covers all necessary context for a complex search tool.

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

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

Schema coverage is 100%, so baseline is 3. Description provides examples for query but does not add substantial new semantics 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 'Semantic search INSIDE a fetched record' with specific action, resource, and mechanism. It differentiates from sibling tools by pairing with ask_pipeworx_grounded for a distinct workflow.

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

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

Explicitly gives a use case: when the record is too large for the prompt. Mentions pairing with ask_pipeworx_grounded but does not cover when not to use or other alternatives.

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

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

Annotations indicate readOnlyHint=false (mutation), idempotentHint=true, destructiveHint=false. The description adds value by detailing OAuth requirement, delivery channel behaviors (always-on feed, email/sms limits, webhook signing and auto-disable). This context is beyond what annotations provide.

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

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

The description is well-structured and front-loaded with the core purpose. It uses bullet-like formatting for types and delivery channels, making it easy to parse. Every sentence provides necessary information without 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 complexity (3 params, nested objects, no output schema), the description is comprehensive: it explains required account, supported types, delivery behavior, and limitations (e.g., 10 SMS/day). The return value (subscription id) is stated. It leaves no critical gaps for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: examples for each subscription type (e.g., items in sec_8k), delivery options with specifics like verification and rate limits. This enriches the schema's property descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from siblings like list_subscriptions and recent_alerts by specifying it's for creating new subscriptions, not listing or retrieving alerts.

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

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

The description explains when to use: for proactive monitoring with a Pipeworx OAuth account, noting that anonymous and BYO accounts cannot persist subscriptions. It provides context on supported types and delivery channels, but doesn't explicitly exclude other use cases or mention when not to use beyond the account 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so safety is clear. The description adds behavioral specifics: returns category-bucketed questions with tool+argument shapes. 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 single paragraph that front-loads the main intent with example phrases and covers key aspects. It is concise with no redundancy, though a more structured format could improve skimmability.

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

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

Given the simple tool with one optional parameter and good annotations, the description fully explains the return structure (category-bucketed questions with tool+argument shapes) and usage context. It is complete without an output schema.

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

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

Schema coverage is 100%. The description adds meaning by listing valid topic values (e.g., 'finance', 'pharma') and explaining the effect of omitting vs. including the parameter, going beyond the schema's brief description.

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

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

The description clearly defines the tool as an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It specifies multiple user intents and distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by indicating it teaches how to call meta-tools.

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

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

The description explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It explains arguments (omit for full spread, pass topic to focus). It lacks explicit exclusions for alternatives but provides clear 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?

Discloses that the row is deactivated (not deleted) and why, adding context beyond annotations. Annotations indicate non-destructive and idempotent, which align with soft deactivation.

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

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

Two sentences, front-loaded with the action, no wasteful 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?

Covers ownership, deactivation behavior, and link to historical events. With no output schema and simple parameters, it's sufficiently complete for tool 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% and the schema describes 'id' as 'Subscription id (uuid) returned by subscribe'. The description adds no further parameter details, so baseline 3 applies.

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

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

Description clearly states 'Cancel a subscription by id', with a specific verb and resource, distinguishing 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?

Explicitly says 'Ownership is enforced — you can only cancel your own subscriptions', guiding when to use and not use, and mentions 'historical events stay available via recent_alerts' as an alternative 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?

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds valuable behavioral context: it returns a verdict, structured form, actual value with citation, and percent delta, and it replaces 4-6 sequential calls. No contradictions with annotations.

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

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

The description is well-structured with examples, use case, scope, output, and value proposition. The list of natural-language triggers could be slightly shortened, but it remains efficient and front-loaded with the most important information.

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

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

Given the complexity of claim verification and lack of output schema, the description adequately explains the return format (verdict, structured form, actual value, citation, delta) and domain (financial claims). It does not cover error cases or limitations on time periods, but overall it is sufficiently complete.

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

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

Schema coverage is 100% and the schema already describes the 'claim' parameter as a natural-language factual claim with examples. The description adds illustrative examples but does not significantly enhance meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool verifies factual claims using natural language, with specific resource and scope (company-financial claims for public US companies via SEC EDGAR + XBRL). It effectively distinguishes from sibling tools by highlighting the domain and the fact that it replaces multiple sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and limits to financial claims. It provides clear context for when to use but does not explicitly mention when not to use, which is implied by the scope.

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