Pixabay

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds value by disclosing the default free model, the need for a BYO key for Anthropic probes, and the return format. 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 consists of two efficient sentences. The first sentence captures the core function and output. The second adds essential details on defaults, key usage, and return structure. 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?

For a tool with no output schema, the description provides a thorough overview of the return format (per-model score, confidence, signals, raw_response + combined view). It covers parameters, use cases, and cost implications, making it self-contained.

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

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

Input schema coverage is 100% with clear parameter descriptions. The description adds extra context (e.g., 'free default', 'BYO key — you pay Anthropic directly') that goes beyond the schema, aiding parameter understanding.

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

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

The description clearly states the action ('probe one or more LLMs'), the resource ('a business / brand / product / topic'), and the output ('score visibility (0-100) per model'). It distinguishes itself from siblings like 'entity_profile' and 'scan_competitor_ai_presence' by focusing on LLM knowledge visibility scoring.

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

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

The description provides clear context on when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default model and optional API key. It does not explicitly state when not to use or compare with sibling alternatives, but the usage is well-defined.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context about routing to 3,668 tools and returning structured answers with stable citation URIs, which goes beyond what annotations provide.

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

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

The description is detailed but front-loads the key preference statement. It includes examples and usage guidance, though it could be slightly more concise. The structure is logical and easy to scan.

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

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

Given no output schema, the description adequately explains the output format (structured answer with citation URIs). It covers input, processing, and output, and combined with annotations, provides a complete picture 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?

The input schema has full description coverage (6 parameters, all described as aliases for 'question'). The description does not add any additional meaning or nuance about the parameters, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: routing a question to specialized tools and returning a structured answer with citations. It distinguishes itself from web search and covers a broad set of factual domains, providing a specific verb (ask) and resource (Pipeworx).

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

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

The description explicitly tells the agent to prefer this tool over web search for factual questions and provides many example queries. However, it does not differentiate from sibling tools like 'ask_pipeworx_grounded' or 'discover_tools', which may reduce clarity for the agent on when to choose among these.

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 details the internal process: same routing as ask_pipeworx, picks right tool, fills args, fetches data, then extracts answer using only tool result. It lists possible refusals with reasons. This adds significant context beyond the annotations (readOnlyHint, idempotentHint, etc.) and is consistent with 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 a single paragraph with multiple sentences, but every sentence provides necessary information. It could be slightly more concise, but the structure is front-loaded with purpose and usage. 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?

Despite no output schema, the description defines the exact return format ({answer, evidence, confidence, source...}) and all possible refusal reasons. This makes the tool's behavior fully understandable without needing an output schema. The complexity is high, and the description covers it 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% (all parameters described). The description does not repeat parameter details but adds context that the question is used for routing to other tools and filling arguments, which is not in the schema. This adds meaningful insight for parameter usage.

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

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

The description begins with 'Hallucination-resistant answer mode for high-stakes reads,' which is a specific verb+resource combination. It clearly distinguishes from the sibling tool 'ask_pipeworx' by noting the extra cost and the use case for quoted or cited answers.

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

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

The description explicitly states when to use this tool ('high-stakes reads,' 'when an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). It also provides alternatives by naming the sibling tool directly.

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

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

The description extensively covers behavioral traits including market resolution, classification, fan-out logic, response shapes, resolver contract, parent event extraction, news fields with fallback handling, safety mechanisms (low confidence short-circuit, closed market detection), and tradeability warnings. This far exceeds the annotations which only declare read-only and idempotent hints.

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

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

The description is quite long and verbose, with multiple paragraphs and many examples. While it is front-loaded with purpose and structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), some content could be summarized or omitted to reduce token usage without losing essential guidance.

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

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

Given the tool's complexity (multiple classifiers, fan-out logic, response shapes, edge cases), the description is exceptionally complete. It covers input formats, behavior, error handling, and output interpretation in detail. Without an output schema, it provides thorough guidance on what the response contains and how to inspect 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?

The input schema has 100% description coverage, so the baseline is 3. The description adds value by explaining default behavior (depth defaults to thorough, include_raw false recommended), providing examples of what 'market' can accept (slug, URL, question text), and clarifying that include_raw=false keeps responses under ~20KB.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' with a specific verb and resource. It distinguishes itself from sibling tools like 'polymarket_edges' and 'validate_claim' by detailing its all-in-one research capability and providing usage examples.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and provides numerous category examples. It also describes when the tool short-circuits (low confidence, closed markets). However, it lacks explicit 'do not use when' guidance or direct comparison 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?

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, assuring safe, non-destructive, idempotent behavior. The description adds significant behavioral context: it explains data sources, handling of off-calendar fiscal years, sorting by primary metric, and return of 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?

The description is somewhat lengthy but each sentence contributes useful information, such as trigger phrases, data sources, and behavioral details. It front-loads critical usage cues. Could be slightly more concise 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?

Despite lacking an output schema, the description adequately explains what is returned: paired data and pipeworx citation URIs per entity, sorted by primary metric. It also details the specific metrics for each type (revenue, net income, etc. for company; adverse-event counts, etc. for drug). The agent can fully understand the tool's outputs.

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 value by explaining acceptable inputs (tickers/CIKs for company, names for drug), giving examples ('AAPL','MSFT'; 'ozempic','mounjaro'), and clarifying min/max items (2-5).

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: side-by-side comparison of 2-5 companies or drugs. It provides trigger phrases ('Compare X and Y', 'X vs Y', etc.) and specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs). It distinguishes itself from sibling tools like entity_profile by explicitly stating 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?

The description explicitly advises using this tool for comparisons, head-to-head, or ranking, and says 'ALWAYS PREFER over sequential single-pack lookups.' It gives query examples. However, it does not explicitly state when not to use it (e.g., for a single entity), which would make it more complete.

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 and destructiveHint=false. The description adds that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas' and that results are 'ready to call directly,' which provides 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?

The description is somewhat verbose but efficiently communicates key points: purpose, usage domains, return value structure. Every sentence adds value, though it could be 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?

Given no output schema, the description adequately explains what the tool returns (tools with names, descriptions, full schemas) and when to use it. The context is complete for an agent to decide when to 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 description coverage is 100%, so the schema already documents all parameters. The description does not add new meaning to parameters but provides natural language examples (e.g., 'analyze housing market trends'), which slightly enhances understanding. Baseline score of 3 is appropriate.

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

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

The description clearly states 'Find tools by describing the data or task' and lists many specific domains (SEC filings, financials, FDA drugs, etc.), making the purpose unambiguous and distinguishing it from sibling tools that are more specialized.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use it versus more targeted tools.

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

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

The description details the tool's behavior: fans out across multiple sources, returns specific fields (cik, filings, fundamentals, patents, news, LEI), and notes the USPTO API sunset date and soft-fail behavior. Annotations already indicate read-only and idempotent, but the description adds valuable context beyond annotations.

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

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

The description is front-loaded with example queries and usage priority, which is effective. It is moderately long but each sentence earns its place by providing necessary behavioral details. Minor redundancy could be trimmed but overall 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?

Even without an output schema, the description thoroughly explains what is returned (cik, company_name, filings with URIs, fundamentals sorted, patents with caveat, news, LEI). It covers limitations and fallbacks, making the tool's capabilities and constraints fully transparent.

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% (2 params, both described). The description adds important context: clarifies that value must be ticker or zero-padded CIK, not names, and explains the meaning of each type. This adds substantial value over 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 uses specific verbs like 'profile' and 'cross-source' and clearly states it returns full details about US public companies. Example queries and listing of data sources make the purpose unmistakable and differentiate it from siblings like 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?

The description explicitly says 'ALWAYS PREFER over chaining single-pack ... lookups when the user asks for a holistic view' and warns that names are not supported, instructing to use resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

The description states 'Delete', which aligns with the 'destructiveHint' annotation. No additional behavioral details are provided beyond what the annotations already convey (e.g., whether it is irreversible, logging, or side effects). The description does not contradict 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 with no filler. The first sentence states the core purpose, the second provides usage context, and the third relates to sibling tools. Every sentence adds value, making it efficient and easily scannable.

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

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

For a simple one-parameter, no-output-schema tool, the description covers purpose, usage context, and tool relationships. Combined with clear annotations and full schema coverage, the agent has enough information to decide when and how to invoke this 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?

With 100% schema description coverage, the input schema already fully documents the 'key' parameter. The description does not add any further explanation or formatting details, so it meets the baseline for this dimension.

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

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

The description clearly states the action ('Delete') and the resource ('a previously stored memory by key'). It distinguishes itself from the related siblings 'remember' and 'recall' by explicitly mentioning them as partners, making the tool's unique role 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 guidance on when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', giving context on its relationships. However, it does not explicitly 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, idempotentHint, and non-destructive. Description adds behavioral detail: 'Fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format.' No contradictions and provides internal steps.

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: purpose, process, output/use cases. Front-loaded and no wasted words. 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?

Tool has 2 params, no output schema, and good annotations. Description covers what, how, and use cases. Minor omission: no mention of site accessibility requirements (e.g., need for public URL) but sufficient for typical 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 description coverage is 100%, so the schema already documents both parameters. Description adds minimal extra value beyond the schema (e.g., output format context). 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 the tool generates an llms.txt file for a URL, with specific verb and resource. It distinguishes from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on file generation rather than scanning or checking presence.

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 three use cases (getting a client's site indexed, drafting for own project, auditing competitor). Does not include when-not-to-use or alternative tools, but 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint; description adds context (returns fields, active by default) without contradicting annotations. Score reflects adequate additional value.

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

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

Two sentences, first states purpose and output, second gives usage guidance. No wasted words, 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 simple list tool with one optional parameter, description covers purpose, output fields, usage context, and non-destructive nature. Complete without needing output schema.

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

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

Schema coverage is 100% with parameter description; description does not elaborate on the parameter beyond implying default behavior. 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 'List the caller's active subscriptions' with specific verb and resource, lists returned fields, and distinguishes from siblings like subscribe/unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear use cases. Implicitly suggests when not to use (for modifications) but no explicit exclusions.

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

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

Annotations already indicate non-read-only and non-destructive, but description adds valuable behavioral details: rate limit of 5 per identifier per day, free, no quota impact. This goes beyond annotations and helps the agent understand constraints.

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 a single paragraph but densely packed with useful information. Could be slightly more structured with bullet points, but it's concise and every sentence adds value. No wasted words.

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

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

Given no output schema, the description doesn't need to explain return values. It covers purpose, usage guidelines, constraints (rate limit, quota), and parameter semantics. Fully sufficient 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?

Even though schema coverage is 100%, the description adds meaningful context: explains the enum values for 'type', advises on message length (1-2 sentences, 2000 chars max), and suggests how to structure 'context'. This adds 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 uses a specific verb ('Tell') and resource ('Pipeworx team') and clearly distinguishes the tool's purpose from sibling tools by focusing on feedback categories (bug, feature, etc.). It's not a tautology and fully conveys what the tool does.

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

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

Explicitly states when to use: for bugs, missing features, praise, etc. Also provides when-not-to-use guidance: don't paste end-user prompts. No sibling tool offers comparable feedback functionality, so differentiation 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 indicate read-only, idempotent, non-destructive behavior. Description adds value by disclosing data source (CF analytics-engine), no PII, caching behavior (5min-1h), which goes 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?

Four sentences, front-loaded with purpose, then use cases and additional details. 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?

For a simple read-only tool with one optional parameter and no output schema, the description covers what it returns, data source, caching, and usage scenarios, providing complete context for an agent.

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

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

Schema coverage is 100% with a clear parameter description. The tool description does not add new parameter semantics beyond what is in the schema, meeting 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 it returns top tools, packs, and call volume based on what other AI agents are calling, with specific verb and resource. It differentiates from siblings like discover_tools by focusing on trending agent activity.

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

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

Provides three specific use cases (discovering hot data sources, confirming canonical choice, aligning use case) but does not explicitly state when not to use or mention alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, covering the safety profile. The description adds significant context: it explains the algorithm (monotonicity checks, partition-sum check), semantic anchor (Jaccard similarity), partition filter, and that calling with no args fails. It does not disclose performance characteristics or response structure in full detail, but given the annotations, the description is adequately transparent.

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

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

The description is front-loaded with the critical requirement and purpose, then dives into details. It is well-structured with distinct sections (SEMANTIC ANCHOR, PARTITION FILTER) and every sentence adds value. It is somewhat long but not wasteful. A minor improvement would be to condense some technical details, but overall it is efficient.

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

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

Given the tool's complexity (two modes, multiple algorithmic checks), no output schema, and the annotations, the description is remarkably complete. It covers failure conditions (no args, low similarity, placeholder fraction), response structure (opportunities[]), and parameter semantics. It explains the partition check and semantic anchor in detail. There is no missing critical information for an agent to understand and use the tool effectively.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds substantial value by clarifying when to use each parameter (recommended for specific market vs cross-event scanning), providing concrete examples (e.g., 'fed-decision-may-2026'), and noting that full Polymarket URLs are also accepted for `event`. This goes well 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) with specific use cases. However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_kalshi_spread, which could cause confusion when selecting the appropriate tool.

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

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

The description explicitly requires one of `event` or `topic`, warns that calling with no args fails, and explains when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It also highlights that cross-event mode catches patterns single-event misses. However, it lacks guidance on when not to use this tool in favor of sibling tools, and does not provide 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, idempotent, and non-destructive behavior. Description adds extensive behavioral details: caching behavior (1h KV-level), diagnostic output explaining empty segments, 24h-move warning, and detailed model family methodologies, going far 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?

Well-structured with sections and front-loaded purpose, but verbose due to technical detail. All sentences add value; conciseness is adequate 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, description thoroughly documents response structure, caching, edge calculation, filtering, and diagnostics. Explains why segments might be empty. Complete for a complex tool.

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

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

Schema covers 100% of parameters with descriptions, providing baseline. Tool description adds significant context on how parameters interact (e.g., tradeable-edge knobs, min_partition_leg_kelly vs min_kelly explanation), improving parameter understanding 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?

Clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, explicitly designed for 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage and bet_research by focusing on edge detection.

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 detailed context on when to use the tool, including description of segments (model_driven, structural_arbitrage, concentrated_longshot) and tradeable-edge knobs. However, lacks explicit statements on when not to use it or alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: explains modes, response structure (leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and conditions for meaningless spreads (temporal mismatch, non-equivalent bet 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?

Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded core function. Slightly verbose but every sentence adds necessary context; could be trimmed slightly 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?

Covers the complex cross-venue spread computation, explains all relevant output fields without an output schema, addresses edge cases (temporal misalignment, non-equivalent bet shapes), and warns about limited tradeability of pre-mapped topics. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value beyond schema by explaining the topic list, override behavior, and providing examples. It clarifies that topic overrides the other parameters when used.

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

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

The description clearly states it computes spreads between Kalshi and Polymarket for the same resolving question, with two modes. It distinguishes from sibling tools (e.g., polymarket_arbitrage, polymarket_edges) by specializing in cross-venue spread analysis and safety checks.

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 usage modes (topic shortcuts and explicit pairings) and warns that pre-mapped topics often return compatibility_warning, implying limited tradeability. Provides guidance on interpreting safety fields like compatibility_warning and temporal_alignment.

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 value by explaining scoping to an identifier and pairing with sibling tools, but does not detail error handling for missing keys.

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 efficient, front-loading the core action, and every sentence provides necessary context 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?

For a simple tool with one optional parameter and no output schema, the description covers all essential aspects: purpose, usage, scoping, and relations to siblings.

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

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

With 100% schema coverage, the description still adds meaning by explaining that omitting the key lists all keys, and provides usage context for the parameter.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, using specific verbs. It distinguishes itself from siblings (remember, forget) and provides concrete examples like user's target ticker.

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 when to use (look up stored context) and hints at alternatives by mentioning remember and forget. However, it does not explicitly state when not to use or provide exclusions.

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

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

Contradicts annotations: description states mark_read:true flags events read, implying state modification, but annotations have readOnlyHint=true. Also idempotentHint may be violated. This is a serious inconsistency.

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?

Reasonably concise: two sentences, front-loaded with verb and resource. Second sentence is packed but clear. Could be slightly more structured, but overall 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?

No output schema, yet description covers return fields, filter parameters, mark_read side effect, and alternative access. Complete for a read tool with 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?

Adds substantial meaning beyond schema: explains filter by type/since, mark_read behavior, and what each returned event contains (source, citation_uri, raw payload). Schema coverage is 100% but description enhances understanding.

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

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

The description clearly states it pulls fired events from subscription feed and returns recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes from siblings like list_subscriptions by focusing on reading 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?

Provides guidance on when to use (polling works fine) and mentions an alternative access method (direct API). Does not explicitly state when not to use, but implies it's for reading recent alerts.

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

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

Discloses fan-out to multiple sources (SEC, GDELT/GNews, USPTO), fallback behavior, and soft-fail for USPTO. Adds detail beyond readOnlyHint and idempotentHint annotations.

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

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

Single paragraph with dense info; front-loaded with examples. Slightly long but economizes words 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?

No output schema, but description clearly states return structure (changes[], total_changes, URIs). Covers edge cases (rate limits, API sunset).

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 all 3 params 100%, but description adds value by explaining relative shorthand for since and clarifying type is only '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?

Description clearly states the tool retrieves 'what's new' for a company in a given window, with examples. It distinguishes from sibling tool entity_profile which handles static profiles.

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 entity_profile instead for static profile. Also provides example queries like 'What's new with X'.

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

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

The description adds value beyond annotations: it explains memory scoping by identifier, persistence differences between authenticated and anonymous users, and lifetime (24 hours for anonymous). Annotations already indicate non-destructive and idempotent nature. The description 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 concise with four sentences, each conveying essential information. It is front-loaded with the core purpose and expands logically to usage, retention, and pairing. No superfluous 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 low complexity (2 required params, no nested objects, no output schema), the description covers all necessary context: purpose, when to use, persistence behavior, and relationships to 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%, so parameters are already documented. The description adds extra context with examples of valid keys (e.g., 'subject_property', 'target_ticker') and values (any text), which helps the agent form correct key-value pairs.

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

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

The description clearly states the verb 'Save data' and the resource 'the agent will need to reuse later'. It explicitly distinguishes from sibling tools like 'recall' and 'forget' by mentioning pairing, and provides specific use cases like resolved ticker, target address, etc.

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: when discovering something worth carrying forward, with concrete examples. It also mentions pairing with recall and forget, giving context for alternatives. However, it lacks explicit 'when not to use' or exclusions.

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

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

Annotations already declare readOnly, idempotent, etc. Description adds that it 'cascades through several lookup endpoints internally' and replaces 2-3 manual lookups, explaining internal behavior. Provides output format 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?

Concise 4-5 sentences, well-structured with user intents first, then usage guidance, then detailed type descriptions. 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?

Fully explains tool's purpose, when to use, parameter details, and output format for each type. No gaps given the tool's simplicity and absence of 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. Description adds examples for each type, explains auto-disambiguation for company, and clarifies valid inputs for value parameter, providing extra guidance.

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 resolves a name to a canonical identifier, with specific examples of user intents and supported entity types. Distinguishes from siblings by noting it replaces manual 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 to use 'FIRST whenever you have a name but need an ID.' Lists supported types and what they return. Could mention when not to use (e.g., if ID already known) or alternatives among siblings, but context is clear.

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

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

Annotations (readOnly, openWorld, idempotent) cover safety aspects. Description adds details about probing with ai_visibility_check, ranking by score, and output fields (score, confidence, signal density), providing beyond-annotation process and outcome context.

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

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

Four straightforward sentences: purpose, process, use case, output. Each sentence adds unique information with no redundancy or filler. Front-loaded with core 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?

Explains input (entities, models, apiKey, context) and output format (ranked list with scores and density). Does not mention entity count limit (2-8 from schema) or error scenarios, but given no output schema, the output description is adequate.

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

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

Schema covers 100% of parameter descriptions. The description adds semantic nuance: 'First entry treated as the subject for narrative', which aids agent understanding beyond schema. No other extra meaning added, but the addition is valuable.

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 specifies the verb 'compare' and resource 'AI visibility', describes side-by-side ranking, and distinguishes from sibling 'ai_visibility_check' by stating it probes multiple entities and ranks them.

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

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

Explicitly associates with competitive AI-marketing audits and provides an example question, implying use for multi-entity comparison. Does not directly mention alternatives like 'ai_visibility_check' for single entities, 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 (readOnlyHint, idempotentHint, destructiveHint) are all appropriate. Description adds critical behavioral details: partial failure grace (bundlephobia first measurement can take 5-30s, sources_failed list on timeout), and that remaining sources still return. This goes well 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 concise yet comprehensive. Front-loaded with purpose, then usage, then specific behavior. Every sentence adds value, no fluff. Well-structured with parentheses for details.

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

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

Given the tool's complexity (multi-source, partial failure, no output schema), description covers all essential aspects: operation, input constraints, return structure (summary block, advisories, links, alternatives), timing caveats, and ecosystem limitations. 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?

Schema coverage is 100% (both parameters described). The description adds clarity: confirms scoped packages (e.g. @types/node) are accepted and implies version defaults to latest. While schema already covers defaults, description reinforces usage and adds 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 is a composite check for npm packages, combining deps.dev and bundlephobia. It specifies the verb (scan), resource (dependency), and scope (safety, popularity, size). It clearly distinguishes from siblings by being a multi-source composite tool.

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

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

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

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. Description adds no further behavioral context, but 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?

Extremely concise but under-specified. Single sentence with no details; lacks structure and fails to provide value beyond the tool name.

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 parameters, good annotations, and existence of output schema, the description is too minimal. It does not explain return values, usage patterns, or how it differs from siblings. Incomplete for an agent to use effectively.

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

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

Input schema has no defined properties (100% coverage), so baseline is 3. Description adds no parameter meaning; examples in schema provide some context but description does not reference them.

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 states 'Image search' which is a verb+resource, but it is too brief and does not differentiate from sibling tools like 'search_videos'. It provides no scope or filtering details.

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

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

No guidance on when to use this tool versus alternatives. No context on prerequisites or limitations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond that, such as which API is used, rate limits, or output format 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?

At two words, the description is overly terse. While conciseness is valued, this brevity comes at the cost of clarity and usefulness, making it under-specified rather than efficiently 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 has zero defined parameters, an output schema, and many sibling tools, the description is critically incomplete. It fails to specify expected parameters, usage context, or how results are returned, leaving an AI agent with insufficient information.

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

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

The input schema has no defined properties (only additionalProperties allowed), and the description does not list or explain any parameters. The examples show 'q', '_apiKey', 'per_page', but without schema definitions or description, an AI agent cannot infer parameter semantics.

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

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

The description 'Video search.' is a near-tautology of the tool's name and title. It offers no specificity about the video source, parameters, or what distinguishes it from sibling tools like 'search_images' or 'search_within'.

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

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

No guidance is provided on when to use this tool versus alternatives. There are many sibling tools (e.g., 'search_images', 'search_within'), but the description does not indicate any usage context or when not to use this tool.

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

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

Discloses embedding model (BGE-base-en), windowing (500-char overlapping), char cap (200K with truncation flag), and output details (offsets, similarity scores). Adds value beyond annotations which only indicate read-only and idempotent.

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 5-6 sentence description. Front-loaded with purpose, then usage, then technical details. 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?

Covers purpose, usage, technical details, output format, and pairing with sibling. No output schema, but description adequately explains return value. Complete for a simple semantic 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% with good descriptions. Description adds example queries and reinforces char limit, but does not significantly expand beyond schema. Baseline of 3 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 semantic search inside a fetched record with specific inputs and outputs. Distinguishes from sibling tools like ask_pipeworx_grounded by describing the use case (saving context) and pairing behavior.

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

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

Explicitly says when to use (record too big for prompt). Mentions pairing with ask_pipeworx_grounded. Lacks explicit when-not-to-use, but context implies small records don't need 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 indicate write, openWorld, idempotent, not destructive. Description adds: returns subscription ID, requires OAuth, type-specific filters, delivery constraints (SMS cap, webhook auto-disable), verification steps for phone. No contradictions.

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

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

Single paragraph but dense with information; each sentence adds value. Could be improved with bullet points for types and delivery channels, but overall efficient 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?

Given 100% schema coverage and no output schema, description thoroughly explains inputs, behaviors, delivery methods, constraints, and success response (returns ID). Covers all necessary information 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 covers 100% with basic descriptions. Description adds rich, actionable context: example parameter values for each type, delivery channel details (E.164 format, webhook signing secret), and conditional requirements (phone verification, webhook auto-disable).

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 'Create a proactive monitoring subscription to a live-data event stream.' Differentiates from siblings like 'unsubscribe' and 'list_subscriptions' by specifying creation of a subscription. Lists supported types with examples, establishing specific verb+resource.

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 when to use: proactive monitoring, live-data events. Mentions prerequisites: Pipeworx OAuth account, not for anonymous/BYO. Covers type-specific usage with parameter examples. Lacks explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: returns category-bucketed example questions with exact tool and argument shapes, drawn from live catalog. No contradictions.

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

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

Description is well-structured: front-loaded with common queries, followed by what it returns, then usage instructions. Every sentence earns its place with no redundancy.

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

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

Given the tool's role as onboarding entry point, the description fully explains return format, argument options, and when to use. No output schema needed because description covers return values.

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

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

Schema coverage is 100% with one optional parameter. Description adds examples of valid topic values ('finance', 'pharma', etc.) and clarifies behavior when omitted (cross-category spread). Adds significant meaning beyond the schema.

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

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

The description clearly states the tool returns example questions categorized by topic, and it is explicitly the onboarding entry point. It distinguishes from siblings by being the introductory tool for new agents.

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

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

Explicit guidance to use FIRST when unsure about Pipeworx capabilities, and to call with no arguments for a full spread or pass a topic for focus. Alternatives like meta-tools are mentioned.

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?

Describes beyond annotations: the row is deactivated, not deleted, so historical events stay available via recent_alerts. Aligns with annotations (non-destructive, idempotent) and adds meaningful context.

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

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

Two sentences, no fluff. Each sentence provides essential information: action, ownership, behavioral nuance.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, and side effects (deactivation). 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 minimal value by linking the id to 'returned by subscribe', but doesn't elaborate on format or validation 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?

Clearly states the action ('Cancel a subscription') and the resource ('by id'). Differentiates from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 ownership enforcement ('you can only cancel your own subscriptions'), guiding when the tool is applicable. Lacks explicit 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: return verdict types, citation mechanism, and efficiency gains over multiple calls. 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 detailed but well-structured and front-loaded. Every sentence adds value; some redundancy in rephrasing could be trimmed, but overall efficient for the complexity.

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

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

Despite no output schema, the description covers return values, scope, limitations, and efficiency. Annotations provide rich behavioral context. Complete for the tool's complexity.

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

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

The single parameter 'claim' is fully described in the input schema. The description adds example claims but no new semantic information beyond the schema. Baseline 3 with marginal addition.

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: natural-language claim verification against authoritative sources. It specifies the domain (company-financial claims) and provides alternative phrasings that distinguish 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?

The description explicitly says to use when needing to check factual correctness, and implicitly limits to financial claims. It lacks explicit direction to siblings for non-financial claims, 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.