Duration

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that it probes LLMs (read operation), mentions default model and BYO key for Anthropic, and clarifies that API calls to Anthropic incur direct charges—disclosing cost implications beyond the annotation 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 a single concise paragraph with no filler. It front-loads the core purpose and immediately provides key behavioral and parameter guidance. Every sentence adds value.

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

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

Despite no output schema, the description explains the return structure (per-model score, confidence, signals, raw_response + combined view). It covers all necessary context: input, behavior, output, and use cases.

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 all 4 parameters. The description adds value by specifying the default model for 'models' parameter, explaining that '_apiKey' enables Anthropic probing with user payment, and clarifying that 'context' helps disambiguate—going beyond schema descriptions.

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

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

The description clearly states the tool's action ('probe one or more LLMs'), resource (LLMs for brand/business/product/topic), and output (visibility score 0-100 per model). It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on per-model scoring and AI-marketing audits.

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

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

The description gives clear usage contexts: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains default behavior and optional apiKey for Anthropic but does not explicitly exclude scenarios or compare to sibling tools.

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

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

Description adds value beyond annotations by stating it is a fast, one-call entry point, works on every tier, and returns stable citation URIs. No contradiction with readOnlyHint or other 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 well-structured and front-loaded with key instructions, though slightly lengthy. Each sentence adds value, covering when, how, and examples.

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 lack of output schema, the description fully covers purpose, usage, behavior, and alternatives. 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% with clear parameter names and descriptions. Description repeats that question is natural language and provides examples, but doesn't add significant new meaning 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 the tool routes factual questions to a vast set of sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly recommends use over web search for factual questions, provides many examples, and specifies when to use alternative tools (ask_pipeworx_grounded for single answer with evidence, deep_research for broad questions).

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

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

The description adds significant behavioral context beyond the provided annotations, such as the source-preference ranking mechanism and that it is a fully working router, not a fallback. 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 80 words) and front-loaded, with each sentence adding distinct value: identity, usage instruction, and clarification of stability.

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

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

The description provides sufficient context for an agent to understand the tool's purpose, behavior, and relationship to the stable sibling. It lacks details about the response shape, but since it states 'same response shape' as ask_pipeworx, it is acceptable.

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 covers all parameters (100% coverage) with descriptions. The tool description does not add additional parameter semantics beyond stating it accepts a natural language question, so baseline score of 3 is appropriate.

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

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

The description clearly states it is a beta version of a universal router that handles natural language questions, routing to over 5,000 tools. It explicitly distinguishes itself from the sibling 'ask_pipeworx' by noting it includes candidate routing improvements.

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

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

The description advises using it exactly like 'ask_pipeworx' when wanting the newest routing, and notes its results are compared against the stable router. However, it does not explicitly state when not to use it, though the stable sibling is implied as the alternative.

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 adds critical behavioral details: hallucination resistance, extraction-only from tool result, explicit refusal reasons, and cost of extra LLM call. 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 and front-loaded with purpose, then details. Every sentence adds value, though slightly verbose. Could be tightened but remains clear and efficient.

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

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

Despite no output schema, the description fully explains return format on success and all possible refusal reasons, making the tool's behavior completely 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% with all parameters documented as aliases for 'question'. The description mentions routing but adds no new semantic detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states this is a 'Hallucination-resistant answer mode for high-stakes reads' and explains it uses only tool results to extract answers. It distinguishes from sibling 'ask_pipeworx' by noting extra cost and use case for quoted/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?

Explicitly provides when to use (answers that will be quoted, cited, or acted on, with examples) and when not to (prefer 'ask_pipeworx' for casual lookups), clearly directing the agent.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description goes far beyond: details fan-out to data sources, resolver confidence (high/medium/low/none), handling of closed markets, cancellation rules, liquidity warnings, and short-circuit behaviors. Contradicts no 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?

Long but well-structured with clear sections (CLASSIFIERS, FAN-OUT, RESPONSE SHAPES). Every sentence adds information, though some redundancy exists. Front-loaded with core purpose. Appropriate 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 response shapes, market fields, analysis block, evidence keys, resolver contract, parent event extraction, news error handling, and safety mechanisms. Fully equips an agent to use and interpret results.

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

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

Schema covers 100% of parameters, but description adds extensive context: examples for market_input, depth options with defaults and contrast, include_raw with size implications. Adds far more meaning than the schema alone.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data in one call. It specifies input types (slug, URL, question text), output (evidence packet + comparison), and intended use cases like 'should I bet on X'. This distinguishes it from sibling tools focused on other aspects.

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

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

Explicitly states when to use: for researching specific bets. Includes extensive context on when it may not work (low-confidence matches, closed markets). However, does not explicitly contrast with sibling tools for alternative scenarios.

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

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

Annotations already indicate safe read-only, idempotent, non-destructive behavior. Description adds key behavioral details: returns sorted by primary metric, handles off-calendar fiscal years correctly, returns paired data with citation URIs, and uses one parallel call.

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, highly efficient. Starts with trigger phrases, then purpose, then type details, then sorting and return format, then efficiency claim. 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?

For a 2-param tool with no output schema, the description adequately covers input syntax, data sources, output characteristics (sorted, paired data, citation URIs), and use case context. No gaps given sibling tools and 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 coverage is 100% so baseline is 3. Description adds valuable semantics: explains the type enum with specific data sources, specifies values must be tickers/CIKs or drug names (2-5), and hints at returned fields per type.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific data sources per type. It distinguishes from siblings like entity_profile (single entity) and the trigger phrases make purpose immediately clear.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups' and quantifies efficiency gain (replaces 8-15 lookups). Provides context for when to use and implies alternatives for single-entity queries.

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 false. Description adds rich behavioral context: account required, paid plan for 'thorough', parallel decomposition, return format (findings with evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[]), semantic excerpting, hop field, and expected latency (15-90s). 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 every sentence serves a purpose. Front-loads critical account requirement and comparison with sibling. Sections are logically ordered (requirements, purpose, usage guidance, behavior details, fallback/alternatives). Minor redundancy in emphasizing 'NOT open-web search' could be pruned slightly, 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?

Despite no output schema, description fully explains return findings packet (evidence, confidence, source, fetched_at, citations, gaps, contradictions) and provides latency expectations. With 2 parameters and rich annotations, the description leaves no critical missing information for an AI 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% (both parameters describe). Description adds substantial value beyond schema: explains depth values (quick=3, standard=5, thorough=8) with detailed behavior (gap recovery, contradictions scan, iterative hops). Clarifies 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?

Description clearly states tool is for grounded multi-source research across 1318 structured data sources via parallel decomposition, distinguishing it from open-web search and sibling tools like ask_pipeworx and ask_pipeworx_beta. It specifies verb ('researches'), resource ('structured data sources'), and unique behavior (parallel tool routing, findings packet with citations).

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: 'Best for broad/multi-part questions over structured data'. Also states when not to use: 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Provides alternatives: ask_pipeworx for single lookup or live news. Includes account requirements and tier information.

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. The description adds valuable context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No contradictions.

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

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

The description is moderately long but efficient, front-loading the core purpose and examples. Every sentence contributes; slightly more conciseness could be achieved, but it's well-structured.

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

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

Given the tool's simplicity (one required parameter, no complex nesting), the description fully covers purpose, usage, return format, and example queries. It is complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions the query field and its aliases but adds minimal new meaning beyond the schema's own descriptions and examples.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, FDA drugs, etc.) and differentiates itself from sibling tools by positioning it as the first call to discover the option set.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set'. It gives clear context for when to use, though it does not explicitly state when not to use or name specific 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds valuable context: parallel execution, multiple data sources with specific details (SEC, XBRL, USPTO with sunset note, GDELT→GNews fallback, GLEIF), and return fields. 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 a single dense paragraph but front-loaded with examples and usage guidance. It could be more structured (e.g., bullet points for return fields), but it remains concise and informative with no wasted sentences.

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

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

Given no output schema and high complexity (multi-source, parallel, fallbacks, deprecation), the description is remarkably complete: it enumerates all return components with URI patterns, specifies parameter constraints, and notes the USPTO deprecation. The agent can fully understand what to expect.

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

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

Schema coverage is 100%, and the description adds meaning beyond the schema: it provides examples ('AAPL' or '0000320193'), clarifies that names are not supported, and explains the supported entity type ('company' only).

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: 'full cross-source profile of a US public company in ONE parallel call.' It specifies the verb (profile) and resource (company), and distinguishes from sibling tools like resolve_entity (name resolution) and compare_entities (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?

Explicit guidance is given: 'ALWAYS PREFER over chaining single-pack... when user asks for a holistic view.' It also instructs to use resolve_entity if only a name, and provides example queries and parameter constraints.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds that deletion is by key but does not elaborate on side effects, reversibility, or any permissions required. 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 consists of two concise sentences. The first states the purpose, and the second gives usage guidance. No unnecessary words or redundancy.

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

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

For a simple tool with one parameter, annotations, and no output schema, the description covers the purpose, usage, and relationship to siblings. It is complete and sufficient for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description restates 'by key' but adds no new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states 'Delete a previously stored memory by key.' It uses a specific verb (Delete) and identifies the resource (memory). The presence of sibling tools like 'remember' and 'recall' makes it clear that this tool is for removal, distinguishing it from related 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 lists 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,' providing clear context relative 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds 'keyless, offline,' which reinforces no side effects but does not disclose additional behavioral traits like limits or error handling. Consistent with annotations but adds little 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?

Single sentence, front-loaded with the verb 'Convert,' and efficiently covers input, outputs, and key attributes ('keyless, offline'). 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 tool with one parameter and no output schema, the description is complete: specifies input type, both output formats, and hints at offline operation. Sibling context clarifies its role opposite 'parse_duration.' Annotations further enrich context.

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

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

Schema coverage is 100% with 'seconds' described as 'Total seconds.' The description restates 'number of seconds,' adding no new semantic information beyond the schema. Baseline 3 applies as schema does the heavy lifting.

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

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

The description clearly states the action (convert), input (seconds), and two specific outputs (ISO 8601 duration string and human-readable form). It distinguishes from the sibling tool 'parse_duration' which likely does the reverse.

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

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

The description implies usage for converting seconds to duration strings but does not explicitly state when to use this tool versus 'parse_duration' or any other alternative. No when-not or contextual guidance is provided.

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, destructiveHint=false. The description adds that the tool fetches the page, extracts content, and emits standard markdown, which is consistent. There is no contradiction, and the description transparently explains the process.

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 compact paragraph with no wasted words. It front-loads the main action and output, includes a bulleted use-case list for clarity, and each sentence adds essential 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?

For a tool with 2 parameters and rich annotations, the description covers input, process, output format, and use cases. It lacks detail on error handling or invalid URLs, but overall it provides enough context for an agent to decide and invoke correctly, especially given the output is described as a simple text blob.

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% as both parameters have clear descriptions. The tool description does not add significant new meaning to the parameters beyond what the schema provides, but it does contextualize the url parameter as the target for fetching. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'generate' and resource 'llms.txt', specifies that it fetches a URL and extracts title/description/key links, and lists concrete use cases. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on file 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 explicitly lists three use cases ('getting a client's site indexed...', 'drafting llms.txt...', 'auditing how an AI crawler would see a competitor'), providing clear guidance on when to use the tool. It lacks explicit 'when not to use' or alternative tool references, but the use cases are sufficient.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds that it returns specific fields and differentiates between active and optionally inactive subscriptions. No contradictions.

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

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

Two sentences: first defines action and output, second provides usage guidance. No filler, front-loaded with key 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?

The description lists return fields and provides usage context. No output schema, but the tool is simple. Could mention pagination or other details, but adequate given annotations.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add extra meaning for the 'include_inactive' parameter 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 action ('List') and resource ('the caller's active subscriptions'). It lists specific return fields and contrasts with sibling tools by mentioning usage for review and 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 when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' Does not explicitly state when not to use, but context with siblings makes it clear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable detail: 'keyless, offline' suggests no external dependencies, and notes the approximation basis (months=30d, years=365d) which is beyond annotation scope.

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 redundant information, front-loaded with the essential purpose. Every word adds value.

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

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

For a simple parsing tool with one parameter and no output schema, the description fully covers what the tool does, the nature of the output (components and seconds), and key behavioral details (approximation, offline). 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 covers the parameter with 100% description, but the tool description adds extra examples ('PT1H30M', 'P1Y2M10DT2H') and context ('keyless, offline') that enhance understanding beyond the schema's basic description.

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

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

Description clearly states the tool parses ISO 8601 duration strings into components and approximate total seconds. The verb 'Parse' and resource 'duration string' are specific, and it distinguishes from the sibling 'format_duration' by being the parsing counterpart.

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

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

The description implies usage for parsing durations but does not explicitly state when to use this tool over alternatives like 'format_duration'. No exclusions or context for when not to use are provided.

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

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

The description discloses important behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, and doesn't count against tool-call quota. It also explains that the team reads digests daily, setting expectations for response time. 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 concise, front-loaded with the purpose, and uses bullet points in a single paragraph. Every sentence adds 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 lack of output schema, the description adequately informs the user about the feedback pipeline. It covers usage context, limitations, and expected outcomes, making the tool self-explanatory.

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

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

The input schema already has high-coverage descriptions (100%). The description adds value by emphasizing message specificity and instructing not to include end-user prompts, which provides practical guidance 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 is for sending feedback to the Pipeworx team about bugs, features, data gaps, or praise. It uses specific verbs ('Tell') and distinguishes itself from sibling tools by being exclusively for communication, not data retrieval or manipulation.

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 the tool: for bugs, feature requests, data gaps, or praise. It also warns against pasting end-user prompts and provides rate-limit and quota info, giving clear context for appropriate usage.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds valuable behavioral context beyond these: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses data source, privacy handling, and caching behavior, which is critical for agent understanding. 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, front-loading the core functionality followed by bullet-pointed use cases and a brief technical note. Every sentence adds value, but it is slightly verbose (e.g., 'Self-aggregating signal' could be integrated). Overall, it is concise for the amount of information conveyed.

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 one parameter and no output schema, the description provides sufficient context: it explains the output (top tools, packs, call volume), data structure ((pack, tool, count)), and caching. It lacks explicit mention of ranking or sorting order, but the core information is complete. Given the tool's simplicity, it adequately prepares 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 provides 100% description coverage for the single 'window' parameter, including an enum and description. The tool description adds further meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances the agent's understanding of the parameter's semantic impact beyond the schema's technical specification.

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: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses specific verbs ('returns') and resources ('top tools, top packs, total call volume'), and the opening line ('What other AI agents are calling on Pipeworx right now') immediately conveys the essence. While it doesn't explicitly differentiate from siblings like 'discover_tools,' the unique focus on trending calls sets it apart clearly.

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 in a bulleted list: (1) discovering hot data sources, (2) confirming canonical tool choice, (3) alignment with agent needs. It also explains the window parameter's effect ('shorter windows surface what's hot right now; longer windows show steady-state demand') and mentions data derivation and caching, offering comprehensive guidance for when to use the tool.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds extensive behavioral details: the algorithmic steps (monotonicity, partition checks), semantic anchor for similarity, partition filter logic, filler check behavior, and conditions that prevent trading (realizable_edge_pp ≤ 0). This far exceeds 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 comprehensive but somewhat verbose, with all-caps labels for sections (SEMANTIC ANCHOR, PARTITION FILTER) that aid readability. While every sentence adds value, tighter structuring could condense it without losing information. Still well-organized 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?

Without an output schema, the description details the response structure (opportunities[], partition_check, suggested_trade) and edge cases (fill check, placeholder filtering). It also references a sibling tool for custom sizing. The description 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%, but the description enriches both parameters with detailed usage instructions and examples (e.g., event slug 'fed-decision-may-2026', topic seed 'Fed rate decision'). It explains the mode switch and what happens under the hood for each parameter, adding substantial value beyond the schema.

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

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

The description starts with a clear verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) and provides concrete examples, making it easy to understand what the tool does and how it differs from siblings like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly states when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. It gives example inputs and explains the internal logic. However, it does not directly compare against sibling tools or specify when to use alternatives, which would elevate it to a 5.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description goes far beyond, explaining caching (1h KV), filter logic (placeholder-slug, partition overround, Fed bets exclusion), response structure with diagnostics, and edge calculations. No contradictions found.

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

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

The description is dense but well-organized, starting with a summary and then detailing segments, response fields, and knobs. It is front-loaded with the essential purpose. While lengthy, every sentence contributes value given the tool's complexity.

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

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

Despite having no output schema, the description thoroughly explains the response structure, including top-level fields, diagnostics, and edge calculations. It also covers caching, filtering, and usage caveats (Fed bets). For a tool with 9 parameters and no nested objects, it 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?

Schema coverage is 100% with each parameter described. The description adds extra semantics like 'Bump for very thin partitions' for slippage_pp, 'Set to 5000 to drop thin-book opportunities' for min_liquidity, and explains how category_filter and min_partition_leg_kelly interact with Kelly sizing. This provides substantial 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 scans Polymarket markets for edges where Pipeworx data disagrees with market price, targeting 'what should I bet on today'. It distinguishes from siblings by detailing three distinct segment types (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), which differ from pure arbitrage or tracking 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 explains when to use the tool (discovering betting edges without paging hundreds of markets) and provides guidance on controlling output via knobs. However, it does not explicitly state when not to use it or compare to siblings like polymarket_arbitrage. Still, clear context is provided.

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 annotations already indicate readOnly and non-destructive. The description adds substantial behavioral context: it reads from daily snapshots, provides time-series, first_seen, trend, decay, expired opportunities, and limitations like 60-day TTL. 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 detailed and structured with a clear purpose statement, output explanation, and limitations. Though lengthy, each part adds value. Minor improvement could be more bullet-style formatting.

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

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

Despite no output schema, the description fully explains the return structure (tracked, expired, snapshot_dates) and covers limitations. For a tool with 2 optional parameters, this is complete and actionable.

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. The description adds meaning by explaining parameters in the tool's context (lookback, snapshot family) and providing defaults and constraints, enhancing understanding beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering a specific question about how long an edge has existed and if it is shrinking. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical snapshots.

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

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

The description gives context by contrasting fresh and old edges, implying usage when assessing edge persistence. However, it does not explicitly state when not to use it or mention alternatives, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds critical behavioral context such as forced directional risk, thin legs, and clamping of size_usd, without contradicting any annotations.

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

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

The description is dense and informative, with every sentence adding value. However, it could benefit from clearer structuring (e.g., bullet points for modes and return fields) to improve readability.

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

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

Despite no output schema, the description comprehensively lists return fields for both modes, explains parameter defaults and constraints, and covers risk warnings. It is complete for a tool of this 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 description coverage is 100%, but the description adds significant meaning beyond the schema: explains mode-specific behavior for side and size_usd, default side logic, and how size_usd is interpreted differently in each mode.

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 as a realizable-vs-theoretical edge check against live order-book depth, distinguishing between single-market and basket modes. It details specific outputs and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs to use this tool before acting on polymarket_arbitrage signals or for trades above ~$500. Provides rationale about uncapturable theoretical overround and risks of partial basket fills leading to unhedged positions.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. Description adds extensive behavioral details: response structure (leg-by-leg prices, matched spreads, top_spreads_pp), safety fields (compatibility_warning with two cases, temporal_alignment, skipped counters), and explains why spreads may be meaningless. 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 relatively long but well-structured: front-loaded with purpose, then modes, response, safety fields. Every sentence adds necessary information. Some redundancy could be trimmed (e.g., repeating 'pre-mapped ≠ tradeable' at the end), but overall it is 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?

Given the tool's complexity (two modes, cross-venue comparison, safety warnings, no output schema), the description is highly complete. It explains all output fields, warning scenarios, temporal alignment, and skipped counters. Agent can understand how to invoke and interpret results without additional documentation.

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

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

Schema coverage is 100% with all three parameters described. Description adds value by explaining that explicit tickers override topic-mapped sides and providing the list of available topics. It also gives examples of usage. While schema already covers basics, description enhances understanding of parameter interactions and override behavior.

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 is a cross-venue spread tool comparing Kalshi and Polymarket prices for the same resolving question. It specifies two distinct modes (topic shortcuts vs explicit tickers) and contrasts with sibling tools like polymarket_arbitrage by focusing on cross-venue spreads. The verb 'spread' and resource 'Polymarket–Kalshi' are 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?

Description explains when to use each mode: topic for quick macros, explicit for custom pairings. It warns that real spreads are rare and pre-mapped topics often return compatibility warnings. However, it does not explicitly name alternatives like polymarket_arbitrage for intra-venue spreads or compare_entities for general comparison, leaving some guidelines implicit.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds scoping detail ('Scoped to your identifier'), which is valuable 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?

Three sentences, each with distinct purpose: purpose, usage, and scope/pairing. No superfluous 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?

For a simple retrieval tool with one optional parameter, the description covers purpose, usage, scope, and pairing. No output schema needed, and annotations are rich.

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 clear parameter description. The description adds use-case examples but no new parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'retrieve' or 'list' and the resource 'saved keys' or 'values'. It distinguishes itself from siblings 'remember' and 'forget' by specifying it is the retrieval counterpart.

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

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

The description provides clear context for use: 'look up context the agent stored earlier' and pairs with 'remember' and 'forget'. It lacks explicit when-not-to-use instructions but is still 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?

The description states that setting mark_read:true flags events as read, which is a state-modifying operation. However, annotations include readOnlyHint=true, creating a contradiction. The description is transparent about the behavior, but due to the contradiction, the score is 1 per guidelines.

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 4 sentences, each providing necessary information. It starts with the main action and progressively adds details, 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?

The description covers the return values (source, citation_uri, raw payload), all parameters, polling suitability, and alternative access. For a tool with no output schema and 5 optional parameters, this is complete.

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

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

All 5 parameters have schema descriptions (100% coverage). The tool description adds value by providing examples (e.g., 'sec_8k' for type) and explaining the effect of mark_read, which goes beyond the schema.

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

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

The description clearly states 'Pull fired events from your subscription feed.' It specifies the action (pull) and the resource (fired events from subscription feed), distinguishing it from sibling tools like list_subscriptions or subscribe.

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 context for usage, including filtering options and a note that the same feed is available via a script/dashboard endpoint. It does not explicitly exclude alternatives but implies this is for programmatic access vs. scripts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant context: fan-out to multiple sources, fallback mechanisms, and soft-fail for patents. 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 but well-structured: purpose first, then sources, parameters, and fallbacks. Every sentence adds value, though slightly longer than necessary.

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 sources, fallbacks, limited output schema), the description covers behavior, input semantics, and output format (changes[], total_changes, citation URIs). No critical 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%, so baseline is 3. The description elaborates on the 'since' parameter with format examples and relative shorthand, and clarifies 'value' accepts ticker or CIK. Adds meaningful context 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 explicitly states the tool's purpose: a change feed aggregating SEC filings, news, and patents for a company in a given time window. It uses clear action verbs and distinguishes itself 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 concrete example queries and explicitly tells when to use the alternative tool 'entity_profile' instead. Also explains fallback logic between GDELT and GNews.

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: scoped by identifier, persistence for authenticated vs anonymous, 24-hour retention. No contradiction with annotations.

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

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

Four sentences with clear structure: purpose, use case, scoping/persistence, complementary tools. 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?

Thorough for a simple key-value store: explains what, when, how, and related tools. No gaps given no output schema or nested objects.

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 examples and reinforces key-value pair concept, improving 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?

Clearly states 'Save data the agent will need to reuse later', specifying verb and resource. Distinguishes from siblings by naming recall and forget.

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

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

Explicitly says 'Use when you discover something worth carrying forward... so you don't have to look it up again.' Describes pairing with recall and forget.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive traits. The description adds behavioral detail: it explains that each call cascades through multiple lookup endpoints internally and replaces 2-3 manual lookups. This provides transparency beyond the 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?

The description is well-structured with query examples at the start and a breakdown of supported types. It is informative but slightly verbose with five sentences. However, every sentence adds value, so it earns a 4 rather than a 5.

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

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

Despite lacking an output schema, the description fully covers the tool's behavior: it lists return values for both entity types, explains internal cascading lookups, and describes input flexibility. It is complete given the tool's complexity and the available schema and 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 coverage is 100% with both 'type' and 'value' described. The description adds significant meaning by detailing the exact outputs for each type (e.g., company returns ticker, CIK, company_name, and URI; drug returns RxCUI, ingredient, brand, URI). It also clarifies input formats (ticker, CIK, name) and provides auto-disambiguation context, surpassing what the schema alone offers.

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

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

The description specifies the exact action: resolving user-spoken names to canonical identifiers. It provides concrete query examples ('What's the ticker for...', 'find the CIK for...') and lists supported entity types (company, drug) with detailed outputs. This clearly distinguishes the tool's purpose from sibling tools like compare_entities or entity_profile.

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

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

The description explicitly states 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. However, it does not explicitly mention when not to use this tool or name specific alternatives, though the context implies it for identifier resolution.

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, and destructiveHint=false. The description adds value by revealing that it internally calls ai_visibility_check for each entity, describes the output as a 'ranked list with score, confidence, signal density,' and does not contradict any annotation. The disclosure is sufficient given the annotation coverage.

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

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

The description is three sentences long, front-loaded with the core purpose, and every sentence adds value (purpose, method, example use case). 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?

Despite having no output schema, the description explains the return format (ranked list with score, confidence, signal density per entity). It covers the number of entities (2-8), the internal use of ai_visibility_check, and the optional context parameter. For a tool of this complexity, the 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 description coverage is 100% (all four parameters have descriptions). The description adds meaning beyond the schema by explaining that the first entity is treated as the 'subject' and the rest as competitors, and that the models parameter defaults to workers-ai. This helps the agent understand parameter roles.

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-resource pair ('Compare AI visibility... side-by-side') and clearly distinguishes from sibling tools like ai_visibility_check (which probes a single entity) by stating it probes multiple entities and ranks them. It also references competitive AI-marketing audits, making the purpose immediately clear.

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

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

The description explicitly states this tool is 'useful for competitive AI-marketing audits' and provides an example question, giving clear context for when to use it. However, it does not explicitly state when not to use it or differentiate from the sibling tool compare_entities, which could also compare entities across different dimensions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: 'Partial failures degrade gracefully — bundlephobia's first measurement ... can take 5-30s; sources_failed will list it if it times out', 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?

The description is a single dense paragraph, but every sentence adds value and the core purpose is front-loaded. It is efficient given the information density; slightly long but not wasteful.

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

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

Despite having no output schema, the description lists the summary block fields (is_latest, license, etc.) and explains partial failures, timing, and alternative versions. This covers behavior and return values sufficiently 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% (both parameters have descriptions). The description adds context about scoped packages being accepted and version defaulting to latest, but this is minimal additional meaning beyond the schema. 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 uses specific verbs and resources: 'Composite check', 'fans out across deps.dev and bundlephobia', explicitly mentioning 'is X safe/popular/small' and 'what does adding lodash cost me'. It clearly distinguishes from sibling tools and states 'NPM ecosystem only in v1'.

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

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

The description explicitly states when to use this tool ('Use whenever an agent asks...') and provides alternatives for other ecosystems ('PyPI/Maven/Cargo/Go fall under deps.dev:version directly'). This gives clear usage context and when-not-to-use.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description adds technical details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. 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?

Very concise: four sentences front-loaded with purpose and usage, then technical details. 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?

Even without output schema, description explains return format (passages with offsets and similarity scores), technical behavior, and limitations (truncation). Complete for 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 has 100% coverage with descriptions for all 3 parameters. The description reinforces but adds minimal new semantics beyond schema defaults and examples. Baseline 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?

The description clearly states the tool does semantic search inside a fetched record, with specific examples (SEC 10-K, article) and distinguishes from sibling tools like ask_pipeworx_grounded by explaining their pairing.

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

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

Explicitly tells when to use: when the record is too big for the prompt, and pairs with ask_pipeworx_grounded for grounding. Provides clear context for use vs alternatives.

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

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

Annotations include readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds context like requiring OAuth, an SMS cap of 10/day, and webhook signing details. However, there is a contradiction: idempotentHint=true suggests the tool can be safely called multiple times, but the description says it returns a new subscription id each time, implying non-idempotent creation. This inconsistency reduces 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 relatively long but well-structured: first sentence states core purpose, then requirements, then types with examples, and finally delivery channels. Each section is informative, but some redundancy (e.g., SMS cap mentioned twice) could be trimmed. Front-loaded with purpose and requirements.

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

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

Given 3 parameters, all described in schema with extra detail in description, and no output schema, the description adequately covers what the tool returns (subscription id), prerequisites (OAuth), limitations (SMS cap, webhook auto-disable after 10 failures), and type-specific parameter structures. No missing essential context for an AI 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%, so baseline is 3. The description adds significant value by providing detailed examples for each subscription type (e.g., sec_8k with items codes, polymarket_edge with topic), and explains the structure of delivery channels (email, sms, webhook) with constraints like phone verification and 10/day cap. This adds 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 title 'Subscribe to Alerts' and description clearly state the tool creates proactive monitoring subscriptions to live-data event streams. It distinguishes from siblings like 'unsubscribe' and 'recent_alerts' by focusing on creation. The description uses specific verbs and resources, making the purpose unambiguous.

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

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

The description explicitly states 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)', providing a clear prerequisite. It lists supported types and examples, but does not explicitly state when not to use this tool vs alternatives, though it implicitly differentiates from 'recent_alerts' for pulling feed. Slight lack of when-not guidance.

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

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

Annotations already declare safe read-only behavior. The description adds useful context: returns shape of exact tool+argument, can be called with no args or with topic. 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 somewhat lengthy but well-structured and front-loaded. Every sentence adds value, including query variations and parameter details. 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 simplicity of the tool (1 optional param, no output schema, safe annotations), the description fully covers what the agent needs: purpose, when to use, parameter details, and return format.

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 description for the only parameter. The description adds meaning: lists example topic values, explains behavior when omitted vs provided, and clarifies the output format.

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

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

The description explicitly states the tool's purpose as the onboarding entry point, returning category-bucketed example questions. It uses specific verbs ('returns', 'use this FIRST') and distinguishes from siblings like ask_pipeworx.

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

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

The description clearly states when to use the tool ('first when you do not yet know what Pipeworx can do') and provides explicit alternatives ('or to learn how to call the meta-tools'). It also explains the optional topic parameter and its effect.

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, non-destructive, and idempotent behavior. The description adds value by detailing ownership enforcement and soft deactivation (row deactivated, not deleted, with historical events preserved). 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 two sentences, front-loading the action and ownership constraint, and efficiently explaining the deactivation behavior. No redundant or 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?

For a simple tool with one parameter and no output schema, the description covers purpose, behavioral traits, and ties to recent_alerts. It is fully sufficient for correct agent invocation.

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

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

Schema coverage is 100% and already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description adds no new parameter information 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 'Cancel a subscription by id' with specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by indicating 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?

The description provides clear context, noting ownership enforcement ('only cancel your own subscriptions'). It implies use when you want to cancel a subscription, but doesn't explicitly mention alternatives or when not to use.

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

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

The description adds significant behavioral details beyond annotations, such as 'exact percent-delta math,' 'automatic fall-through' to grounded pipeline, and the return format (verdict, citation, reasoning). Annotations already indicate read-only and idempotent, and the description aligns with those.

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 every sentence adds value. It front-loads the purpose with examples, then explains paths, parameters, and output. It could be slightly tighter, but it is well-organized and comprehensive.

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

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

Despite lacking an output schema, the description fully explains the return values (verdict types, actual value, citation, reasoning). It covers both claim types, parameter semantics, and fallback behavior. No gaps are evident given 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 both parameters described. The description adds extra semantics: for 'tolerance_pct,' it advises setting 1–2 for hallucination detection and explains default behavior ('implied by wording, capped at 5'). This goes beyond the schema's basic description.

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

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

The description uses specific verbs ('verify', 'check', 'confirm or refute') and clearly states the resource ('natural-language claim verification against authoritative sources'). It includes example query phrasings and distinguishes between financial and other claim paths, effectively differentiating from siblings.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It outlines the two processing paths (SEC EDGAR for financial claims, grounded pipeline for others) and explains when to override tolerance. While it does not explicitly name alternatives, the guidance is clear and context-rich.

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