Could Have Been Email

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

Annotations indicate read-only, idempotent, open-world, non-destructive. Description adds behavioral details: probes multiple LLMs, default model free, returns per-model scores with confidence and signals, and explains API key requirement for Anthropic. 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?

Three sentences, front-loaded with core action, each sentence adds distinct value: action, model/api key details, return format and use cases. No redundancy or fluff.

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

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

Covers return format (per-model score, confidence, signals, raw_response, combined view) despite no output schema. Mentions limitations (API key required for Anthropic) and use contexts. Missing details on edge cases like entity length limits or error handling, but sufficient for typical use.

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

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

Schema description coverage is 100%. Description adds value by explaining each parameter: 'entity' as thing to ask about, 'models' as selection, '_apiKey' as optional key, 'context' for disambiguation. Provides examples and clarifies optionality beyond schema.

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

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

The description clearly states the verb 'probe' and the resource 'LLMs for what they know about a business/brand/product/topic', scoring visibility per model. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on visibility scoring rather than scanning or 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?

Provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Does not explicitly state when NOT to use or name alternatives, but the context of sibling tools implies differentiation.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by explaining that it routes to 5,529 tools, fills arguments, and returns citations with stable URIs. However, it does not mention potential latency, failure modes, or how it handles unanswerable questions, so it falls just short of a 5.

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

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

The description is longer than typical but well-structured, with clear sections ('PREFER OVER WEB SEARCH', 'STEP UP ONLY WHEN NEEDED') and examples. Every sentence adds value, though it could be slightly tightened without losing meaning.

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 complex routing tool with no output schema, the description is remarkably complete. It covers what it does, when to use it, when to use alternatives, example inputs, and return format (citations). No significant gaps remain for the evaluator.

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

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

Schema description coverage is 100%, with the 'question' parameter and its aliases fully documented. The description adds example questions but does not provide additional semantic detail beyond what the schema already conveys. Thus the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb (ask/routes) and resource (pipeworx tool), and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. It also provides concrete examples of use cases, making the tool's purpose unmistakable.

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

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

The description gives explicit guidance on when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It also mentions it works on every tier and is the default entry point.

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 the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses its experimental nature, that candidate routing improvements may be active live, and that currently no candidate is active. It clarifies 'Falls back to nothing — this IS a full working router' to prevent misconception. This adds substantive behavioral context without contradicting annotations.

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

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

The description is three dense sentences that pack identity, usage, experimental status, and a clarifying fallback note. It is front-loaded with the core identity ('Beta version of ask_pipeworx') and each sentence earns its place with no redundancy or fluff.

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

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

For a router tool with no output schema, the description covers identity, usage, experimental status, and confirms the response shape matches ask_pipeworx. It doesn't directly describe the exact return structure, but pointing to the sibling's response shape mitigates this gap. Given the annotations and full schema, it's largely 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 six parameters (aliases) have descriptions in the schema, with the primary 'question' parameter fully explained. The description only states 'same arguments' and doesn't add further semantic detail beyond the schema. Since the schema is fully self-documenting, a baseline of 3 is appropriate.

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

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

The description opens with 'Beta version of ask_pipeworx: identical universal router (same 5,529 tools, same arguments, same response shape)', which clearly defines the tool's purpose as a variant of ask_pipeworx. It distinguishes from siblings by labeling itself as beta and experimental, and it specifies the exact scope (same tools, arguments, response shape).

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

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

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and provides context that 'results are compared against the stable router to decide what merges.' It also notes the current inactive candidate state, guiding the agent on what to expect. This is clear when-to-use guidance with an implicit alternative (the stable ask_pipeworx).

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 thoroughly discloses behavior: it only uses tool result content, can refuse with specific reasons, returns a structured object with evidence and confidence, and costs an extra LLM call. This adds significant context beyond the annotations (readOnly, openWorld, idempotent, non-destructive) and does not contradict them.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, return format, usage guidance, and cost trade-off. It is front-loaded with the core value proposition and structured logically, avoiding 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 absence of an output schema, the description fully specifies the return object and all refusal reasons. It also addresses when to use vs. alternatives and the additional cost, covering the main operational concerns for an agent selecting this tool.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the natural-language question. The description doesn't add parameter-level details, but it doesn't need to since the schema already fully specifies the inputs. The mention of 'fills arguments' is routing context, not parameter semantics.

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

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

The description clearly states the tool's function: a grounded, hallucination-resistant answer mode that extracts answers only from tool result content. It explicitly differentiates from the sibling ask_pipeworx by emphasizing its refusal capability and evidence-based output.

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

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

It explicitly tells when to use this tool (high-stakes reads, quoted/cited/acted-on answers) and when to prefer the cheaper sibling ask_pipeworx for casual lookups. It also discloses the extra LLM call cost, aiding cost-benefit decisions.

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, openWorld, idempotent), the description details resolver confidence, closed market handling, wide spread warnings, cancellation rule parsing, and fan-out patterns. 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?

Front-loaded with purpose and input format. While lengthy, it uses clear section headers (RESPONSE SHAPES, RESOLVER CONTRACT) to organize information. Some redundancy in fan-out examples, 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?

No output schema, so description fully covers return structure (result.market, analysis, evidence, resolver contract, parent_event, news fields) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). Highly comprehensive.

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

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

With 100% schema coverage, baseline is 3. The description adds value by specifying acceptable formats for the 'market' parameter (slug, URL, question text) and examples. Other parameters are well-covered by 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 opening sentence clearly states the verb 'Research', the resource 'Polymarket bet', and the action of pulling Pipeworx data. The description elaborates on how it classifies and fans out, making it distinct from sibling tools like polymarket_arbitrage.

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

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

Explicit use cases are given: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z'. However, it does not contrast with alternatives like polymarket_edges, which is a minor gap.

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 reveals that it pulls specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. This adds rich behavioral context.

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

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

The description is dense but all sentences add value. It front-loads the core action and usage guidance, then efficiently details data sources and behavior. 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?

Given the tool's complexity (multiple entity types, comparison logic, data sources), the description fully covers what an agent needs: when to use, what data is retrieved, how results are presented, and that it replaces many sequential calls. No output schema is needed for this level of detail.

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 schema covers 100% of parameters, and the description adds substantial meaning by explaining the interpretation of 'values' for each entity type (tickers/CIKs for company, drug names for drug) and the min/max constraints. Examples and the purpose of the 'type' parameter are clearly elaborated.

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 comparisons of 2-5 companies or drugs. It provides example queries and distinguishes itself by recommending use over sequential single-pack lookups, making the purpose very 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?

The description explicitly says when to use the tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and describes what data it retrieves for each type. It gives clear context for its use without excluding alternatives, effectively guiding 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 declare readOnlyHint=true, idempotentHint=true, etc. The description adds what the tool returns, which is partially redundant with the output schema. No additional behavioral traits (e.g., rate limits, data handling) are disclosed.

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 sentence with a clear verb and resource, followed by a brief list of outputs. No filler, well-structured, and all information is essential.

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

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

The tool is simple with 4 parameters and an output schema. The description fully explains what the tool does and what it returns. No additional info is needed for an agent to use it correctly.

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

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

Schema coverage is 100% with all parameters described. The description does not add new semantic meaning beyond the schema. It naturally explains the transcript parameter but gives no extra detail on duration, recurring, or attendee_count.

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 purpose: 'Check if a meeting transcript could have been an email instead.' It lists specific outputs (filler word count, decisions, action items, suggested email) and the tool's name and title reinforce this. No ambiguity.

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?

Usage is implied by the tool's specific function, but there is no explicit guidance on when to use this tool versus alternatives or when not to use it. The description could mention that it is for transcripts only or that it is not for real-time meetings.

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, but the description adds substantial behavioral detail: it is NOT open-web search, it decomposes questions into facets, routes to tools in parallel, returns gaps[] for unanswered facets, never invents answers, may take 15-90 seconds, and semantically excerpts large records. This far exceeds what annotations convey.

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

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

The description is long and dense, but every sentence carries valuable operational information (account requirements, alternatives, latency, limitations, return format). It is front-loaded with the most critical caveat (account required), though it could be more tightly organized. Given the tool's complexity, the length is justified, but a slightly more structured layout would improve scannability.

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

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

With no output schema, the description fully describes the return packet contents, including the fields each finding has, the presence of contradictions[] in certain modes, and the semantics of citations being resolvable. It also covers latency expectations, depth modes, and edge cases (e.g., empty gaps[] for current-news topics). This is a comprehensive description for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully enriches both parameters. For 'depth', it explains the concrete implications of each enum value (number of facets, hop behavior, paid requirement), which the schema only hints at. For 'question', it clarifies that broad/multi-part questions are expected and decomposition is the point. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call', and explicitly distinguishes it from open-web search and sibling tools like ask_pipeworx. It also specifies the output: 'a findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding'.

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 when-to-use guidance: 'Best for broad/multi-part questions over structured data' and when not to use it: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also states account prerequisites and alternatives, making the usage context crystal clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns top-N tools with full schemas and examples, ready to call—value beyond annotations, though annotations already cover safety.

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

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

Front-loaded with the core purpose, lists many domains, and provides clear usage context. Slightly long but each sentence earns its place; minor redundancy in aliases.

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

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

No output schema, but the description fully explains return contents (names, descriptions, schemas, examples) and states results are ready to call—complete for a discovery tool.

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

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

Schema description coverage is 100% with detailed parameter descriptions. The description adds context about 'query' being natural language but largely redundant with 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 ('Find tools by describing the data or task') and lists numerous resource domains (SEC filings, FDA drugs, etc.), clearly distinguishing 'discover_tools' from siblings that focus on specific queries or actions.

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 'Call this FIRST when you have many tools available' and contrasts with 'not just one answer', providing clear when-to-use guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details the multi-source fan-out, specific returned fields, and the patent sunset soft-fail. This adds valuable behavioral context, though could be slightly more concise.

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 information-dense and well-structured with example queries first, then usage preference, then data source enumeration. It could be slightly shorter, but every sentence adds value.

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

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

For a tool without output schema, the description comprehensively lists return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and notes the patent limitation. This is fully adequate for agent understanding.

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

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

Schema coverage is 100% with clear descriptions. The description adds example values (e.g., 'AAPL', '0000320193') and clarifies that names are unsupported, directing to resolve_entity. This enriches the schema's semantics.

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

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

The description uses specific verbs like 'Tell me about' and 'brief me on' and clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call'. It distinguishes itself from sibling tools like resolve_entity and compare_entities.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and clarifies that names are not supported, directing to use resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Description matches annotations (destructiveHint=true) and adds context about use cases. No contradictions; the behavioral intent is clear beyond what annotations provide.

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

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

Two concise sentences; first states the core function, second adds usage guidance. No unnecessary words, 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?

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and behavioral implications, leaving 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 the 'key' parameter described as 'Memory key to delete'. Description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory by key', and distinguishes from sibling tools 'remember' and 'recall' by mentioning them.

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

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

Provides explicit conditions for use (stale context, task done, clear sensitive data) and suggests pairing with remember and recall, giving clear guidance on when to use this tool.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds that the tool fetches the page and extracts title/description/links, providing behavioral insight beyond the annotations. No contradictions.

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

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

Three sentences, each serving a purpose: core action, output details, use cases. Front-loaded and efficient with no unnecessary words.

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

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

For a tool with 2 parameters, no output schema, and clear annotations, the description covers all necessary aspects: input, behavior, output format, and use cases. It is complete without needing the output schema.

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

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

Schema description coverage is 100%, so the schema already explains both parameters. The description mentions the default and max for max_links, but this info is also in the schema. No significant additional meaning is added.

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

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

The description explicitly states the tool's purpose: generating a production-ready llms.txt file for a URL. It details the extraction of title, description, and key links, and the output format. This clearly distinguishes it from sibling tools, which are unrelated.

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

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

The description lists specific use cases (client indexing, drafting, competitor auditing), providing clear context for when to use the tool. It does not explicitly state when not to use, but the use cases cover the intended scenarios sufficiently.

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. The description adds value by listing all return fields (id, type, etc.) and any implied behavior like 'active subscriptions' (default filtering). 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 concise sentences with no filler. First sentence states purpose and return fields. Second sentence gives usage guidance. Every sentence is valuable.

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

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

Given no output schema, the description lists return fields adequately. However, it lacks details on pagination, sorting, or default limits. With annotations covering safety and idempotency, it is mostly complete for a simple list tool.

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

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

Schema coverage is 100% for the single parameter 'include_inactive'. The description does not mention this parameter, but the schema already documents it. No added 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?

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from siblings like subscribe and unsubscribe by indicating this is the listing 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 explicitly advises use cases: 'review what you're monitoring before adding more or to find an id to cancel', implying when to use this tool versus subscribing or unsubscribing. It could explicitly name siblings but the usage context is clear.

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

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

The description discloses significant behavioral traits beyond the annotations: the claim_token flow for retrieving status, the daily rate limit of 5 per identifier, that it's free and doesn't count against quota, and that the team reads digests daily. These details add transparency about side effects and constraints. No contradiction with annotations (readOnlyHint=false is consistent with filing feedback).

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 substantial but every sentence serves a purpose: scope, when-to-use, exclusions, mechanics, token flow, rate limit, and policy. It is front-loaded with the main action and then progressively details specifics. Slightly longer than strictly necessary, but the density of useful information justifies its length.

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

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

Given the tool's complexity (4 params, nested context object, token flow) and no output schema, the description fully covers usage conditions, parameter semantics, response behavior (claim_token), and practical constraints like rate limits and quota exemption. An agent has all the information needed to invoke this tool correctly and know what to expect.

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

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

Schema coverage is 100%, so each parameter is already well-described. The description adds extra value by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})' and 'with no other arguments'), which is not fully captured in the schema. Minor redundancy with the schema descriptions keeps this from a 5.

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

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

The description opens with a specific verb ('Tell the Pipeworx team') and resource, clearly defining the tool's purpose: sending feedback about bugs, missing features, or praise for Pipeworx tools. It distinguishes itself from all sibling tools by scoping to Pipeworx connection tools only and explicitly naming alternative servers it cannot fix.

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 it (bug, feature, data_gap, praise) and when not to ('if the tool came from a different MCP server... file it with that server instead'). It also gives concrete guidance on what to include in the message and how to check on previous reports via the claim_token, fully covering usage context and exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds beyond these: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This provides transparency on data sources, privacy, and caching behavior, which is highly valuable.

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 two well-structured paragraphs. The first sentence front-loads the core purpose. Every sentence adds value, with no redundancy or filler. Use cases are enumerated clearly, and technical details are grouped separately.

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 low complexity (one optional parameter, no output schema), the description covers all necessary aspects: return values (top tools, packs, volume), window options, use cases, data source, privacy, and caching. There are no missing details for an agent to correctly invoke this tool.

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

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

Schema coverage is 100% with a description and enum for the single parameter. The description adds context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances the semantic understanding beyond the raw schema, justifying a score above the baseline of 3.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' with specific time windows. It uses a specific verb ('returns') and resource ('trending data on Pipeworx'), and distinguishes from siblings like 'discover_tools' and 'ask_pipeworx' by focusing on aggregate trends.

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?

Three explicit use cases are provided (e.g., discovering hot data sources, confirming canonical tools). The description also explains when to use different window sizes: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' However, it does not explicitly compare against sibling tools or state when not to use it.

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

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

Provides extensive behavioral detail beyond annotations: semantic anchor (Jaccard ≥0.30), partition filter (placeholder >20% → null), fill check comparing theoretical vs realizable edge with specific threshold (realizable ≤0 → do not trade). Annotations only indicate readOnly, openWorld, idempotent, non-destructive; description adds crucial algorithmic and output behavior.

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

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

Description is lengthy but well-structured with clear paragraphs for each mode, semantic anchor, partition filter, fill check, and response format. A few sentences could be tightened (e.g., repeating 'use this if you know'), but overall efficient for 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?

Given the tool's complexity (multiple modes, edge cases, fill check), the description covers all critical aspects: input parameter semantics, algorithmic logic, filtering conditions, output structure, and trade guidance (when not to trade). No output schema is provided, but description compensates fully. Annotations and schema enrich the picture.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds significant context: event accepts full URLs, topic is a seed question, and explains how each mode affects scanning scope (single-event vs cross-event). Substantially enhances schema meaning.

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

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

Clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, with three distinct operating modes (no args, event, topic). Differentiates itself from sibling tools like polymarket_edges and polymarket_fill_risk by its specific function.

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

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

Explicitly describes when to use each parameter: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic for cross-event scanning'. Does not directly contrast with sibling tools but provides clear usage context. Lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's safe. The description adds significant behavioral context: caching (1h KV-level), model families, filtering logic, diagnostics, and details on edge computation. This goes well beyond what annotations provide.

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

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

The description is lengthy but well-structured: purpose first, then model families, then knobs, then response format. Every segment adds necessary detail. It is front-loaded with the core use case. Could be slightly more concise, but the structure is logical.

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

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

With 9 parameters, three model families, and no output schema, the description is exceptionally complete. It explains every output field (by_segment segments, fed_candidates, diagnostics), caching, and filtering logic. An agent can fully understand inputs, outputs, and behavior 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 description coverage is 100%, so the schema already documents all 9 parameters. The description adds value by explaining how knobs like min_liquidity filter opportunities and how slippage_pp affects edge calculation. It also describes output fields that are parameters' effects, enhancing understanding.

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

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

The description starts with a clear verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly states the tool's purpose and distinguishes it from siblings like polymarket_arbitrage by focusing on data disagreement rather than pure arbitrage.

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

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

The description positions the tool for 'what should I bet on today' and explains when to adjust tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly). It does not explicitly state when not to use this tool versus siblings, but the context is sufficient for an agent to decide.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description supplements this by detailing the returned data structure (tracked, expired, snapshot_dates) and how decay is computed, adding significant behavioral context beyond annotations.

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

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

The description is thorough but slightly lengthy. It front-loads the core purpose effectively, but the detailed response format could be slightly condensed. However, every sentence adds value, and the structure is logical.

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

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

Despite no output schema, the description fully describes the response structure (tracked with fields, expired with lifespan, snapshot_dates). It covers all necessary context for a time-series tool, including data gaps and decay computation.

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

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

Schema coverage is 100% for both parameters. The description adds meaning by specifying defaults (14 for days, '1wk' for window) and constraints (max 30 for days), which the schema only describes minimally. This provides actionable guidance for parameter selection.

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: tracking edge persistence and decay over time, answering the specific question about edge duration and shrinkage. It distinguishes from sibling tools like polymarket_edges by focusing on historical telemetry rather than current 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 implies usage when analyzing historical edge behavior, and contrasts with current edge tools (e.g., polymarket_edges) by discussing time-series data. It also notes limits (60-day TTL, daily closes) but does not explicitly state when not to use or provide alternative selection criteria.

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

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

The description adds rich behavioral context beyond annotations: it walks the ladder, returns slippage, fill verdict, per-leg details, identifies thin legs, and flags forced directional risk. Annotations already mark readOnlyHint=true, idempotentHint=true, etc., and the description aligns perfectly, adding live CLOB interaction details 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 lengthy but well-structured with clear headings for SINGLE-MARKET and BASKET modes. Every sentence adds value, but it could be slightly more concise without losing essential details. Front-loading with a summary line helps.

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, many output fields) and absence of an output schema, the description is highly complete. It lists all return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and explains the risk of partial fills. Annotations cover safety and idempotence, and no gaps remain.

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

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

Schema coverage is 100% with good descriptions, so baseline is 3. The description adds value by clarifying the mutual exclusivity of market vs event, explaining how size_usd differs in single-market vs basket modes, and providing default and clamp ranges. This goes beyond what the schema provides but is not a huge leap.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing between single-market and basket modes. It specifies the exact verb (check) and resource (fill risk), and the presence of sibling tools like polymarket_arbitrage and polymarket_edges shows clear differentiation.

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

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

Explicitly tells when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains when not to rely on theoretical edge on thin books and warns about partial basket fills converting arb to directional position, providing clear context and exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: safety fields (compatibility_warning, temporal_alignment, skipped_cross_type counters), the fact that pre-mapped topics often return warnings, and specific conditions that make spreads meaningless. This goes well beyond the annotations.

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

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

The description is well-organized with sections (TWO MODES, RESPONSE, SAFETY FIELDS) and uses clear formatting (bold, backticks). However, it is verbose: the warning about pre-mapped topics appears twice, and some details (like the explanation of skipped_cross_type subtypes) could be condensed. It earns its place but could be tighter.

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 (leg-by-leg prices, matched spreads, safety fields, counters). It covers edge cases (compatibility_warning conditions, temporal alignment) and provides practical guidance on interpreting results. For a tool of moderate complexity, this is highly 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% (all three parameters described in the input schema). The description adds meaning by explaining the two usage modes: topic as a shortcut and explicit tickers for custom pairings, including override behavior. Examples in the schema further clarify. The description enriches understanding without being redundant.

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 statement of the tool's core function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It explicitly names the two venues and the concept of spread. It details two operating modes (topic shortcuts and explicit tickers) and what the response contains, which clearly distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description explains when the tool should be used (e.g., to compare prices across venues) and includes explicit warnings about when the spread is meaningful or not (compatibility_warning cases, temporal alignment). It implies that for non-equivalent bet shapes the tool says so, guiding appropriate usage. However, it does not explicitly contrast with alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context beyond annotations, such as the scoping mechanism ('Scoped to your identifier') and the pairing with siblings. No contradiction with annotations.

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

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

The description is fairly concise but includes some redundancy (e.g., examples of what to look up). It is front-loaded with the core action, and every sentence contributes useful information. Minor trimming could improve conciseness.

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 an output schema, the description could explicitly state the return format (e.g., the value or a list of keys). However, the examples and context strongly imply the output, so the gap is minor.

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

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

Schema coverage is 100% for the single optional parameter 'key'. The description ('Memory key to retrieve (omit to list all keys)') aligns with the schema description, adding no new semantic information. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool retrieves a value by key or lists all keys, using specific verbs (retrieve/list) and a clear resource (saved memory). It explicitly distinguishes from sibling tools 'remember' and 'forget' by mentioning them and the intended pairing, leaving no ambiguity.

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: 'look up context the agent stored earlier—the user's target ticker, an address, prior research notes'. It also explains scoping ('Scoped to your identifier') and directly pairs with sibling tools ('Pair with remember to save, forget to delete'), giving clear when-to-use and alternatives.

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

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

Annotations declare readOnlyHint=true, but the description describes mark_read:true which flags events as read, a state modification. This is a direct contradiction. Beyond that, the description adds context about polling and return fields, but the contradiction dominates.

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

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

The description is a single, well-structured paragraph with no redundant sentences. It starts with the core function, lists return fields, explains parameters, and ends with alternative access.

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 (5 parameters, no output schema), the description covers all parameters, return fields, behavior of mark_read, and even provides an alternative script access. No major 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 all parameters; description adds value by providing an example for 'type' ('sec_8k'), specifying ISO timestamp for 'since', and explaining 'mark_read' behavior. This aids parameter understanding beyond schema.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying what it returns (source, citation_uri, raw payload). This distinguishes 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 mentions polling works and provides an alternative access method (alerts.json). It explains filtering options but doesn't explicitly state when not to use this tool versus alternatives, though siblings don't directly overlap.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint; the description adds valuable behavioral context: it fans out to multiple sources, describes fallback logic (GDELT→GNews), notes soft-fail for USPTO due to API sunset, explains 'since' parameter formats, and outlines the return structure (changes[], total_changes, URIs). No contradiction with annotations.

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

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

The description is a single paragraph that efficiently packs multiple details (use cases, sources, fallback, return structure, sibling distinction). It is front-loaded with usage examples, but could be slightly more structured for easier scanning. Still, every sentence earns its place.

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

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

Given the tool's complexity (multiple data sources, fallback logic, parameter formats) and the lack of an output schema, the description thoroughly covers how to use the tool, what to expect, and how it differs from a sibling. No gaps remain for correct invocation.

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

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

Schema description coverage is 100%, but the description adds extra meaning: it explains the 'since' parameter's ISO date and relative shorthand formats with examples, recommends '30d' or '1m', and clarifies that 'value' accepts ticker or CIK. This goes beyond the schema's brief 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 starts with concrete user queries (e.g., 'What's new with X') and then explicitly states it's a change feed for a company in a time window via one parallel call. It lists the specific sources (SEC EDGAR, GDELT→GNews, USPTO) and clearly distinguishes itself from the sibling tool 'entity_profile' by stating when to use that instead.

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

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

The description provides explicit example queries that map to the tool's use, and directly tells when NOT to use it by directing to 'entity_profile' for static profiles. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate idempotency and non-destructive behavior. Description adds valuable context on scoping by identifier, persistence for authenticated users vs. 24-hour retention for anonymous sessions, without contradicting 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, no wasted words. Front-loaded with purpose, then usage, then behavioral details, then pairing. Excellent structure.

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

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

Covers all necessary aspects for a simple key-value store: purpose, when to use, persistence behavior, pairing. Could mention overwrite on same key, but idempotent hint implies it.

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

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

Schema covers both parameters with descriptions. Description adds usage examples for keys and values, reinforcing intended use beyond what schema provides.

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

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

Clearly states the tool saves data for reuse across conversations or sessions, with a specific verb ('save') and resource ('data to reuse later'). Distinguishes itself from sibling tools (recall, forget) by its write-only role.

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

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

Explicitly advises when to use ('when you discover something worth carrying forward') with concrete examples. Mentions pairing with recall and forget. No explicit when-not, but context is 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 the annotations (readOnly, idempotent, etc.), the description reveals important behaviors: identifiers are labeled with originating sources, unresolved identifiers are explicitly listed under `unresolved` rather than silently omitted, and LEI/FIGI enrichment degrades gracefully when GLEIF/OpenFIGI are unavailable. It also discloses that each call cascades through multiple internal endpoints.

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 it is front-loaded with usage examples and a clear 'Use FIRST' directive before diving into detailed type explanations. Every section serves a purpose, though some phrasing could be tightened without losing value. It is organized with clear labels (e.g., 'SUPPORTED TYPES') and reads well.

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

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

With no output schema, the description must convey return semantics, and it does so thoroughly: it enumerates the output identifiers (CIK, ticker, LEI, FIGI, RxCUI), explains source labeling, describes the `unresolved` field, and covers graceful degradation. For a tool with two entity types and complex cross-source lookup, this is a complete and self-sufficient description.

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 schema already provides thorough descriptions for both parameters (type enum, value with examples), so the baseline is 3. The description adds value by contextualizing the value parameter ("user-spoken NAME") and clarifying the input formats within the supported types (e.g., "accepts ticker, CIK, or company name"), even though the schema already lists these. It does not add substantial new syntax details beyond what the schema covers.

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 a specific verb+resource+outcome: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It distinguishes itself from siblings by focusing on identifier resolution (vs. entity_profile for profiles) and provides concrete examples of query phrasings.

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

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

The description explicitly tells when to use the tool: "Use FIRST whenever you have a name but need an ID." It also notes that it replaces 2-3 manual lookups, implying it is the preferred shortcut. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also specifies the output fields (score, confidence, signal density). This adds value beyond annotations without contradiction.

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

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

The description is two sentences long, front-loaded with the primary action, and every sentence adds value. No wasted words.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description adequately explains input behavior and expected output (ranked list with score, confidence, signal density). It could benefit from clarifying the ranking order or how tie-breaking works, but is otherwise complete.

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

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

Schema coverage is 100% and each parameter already has a clear description. The description adds context: the first entity is treated as the 'subject', models default to 'workers-ai', and context disambiguates common names. This reinforces and slightly extends the schema meaning.

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 'compare' and a clear resource 'AI visibility across multiple entities'. It distinguishes itself from sibling tool ai_visibility_check by focusing on side-by-side comparison with ranking, and from compare_entities by specifying the domain of AI visibility.

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 the use case 'competitive AI-marketing audits' and provides an example question. It implies when to use (multi-entity comparison) but does not explicitly exclude scenarios where a single probe would suffice, nor does it name alternatives like ai_visibility_check for single entities.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. No contradiction with annotations.

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

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

The description is detailed but well-structured, with a leading parenthetical summary, then use case, return block details, ecosystem scope, and failure behavior. It is dense but not overly verbose; however, it could be slightly more concise.

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

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

Given the tool's complexity (composite, two services, partial failures), the description covers key aspects: what it returns (summary block, per-advisory detail, links, alternative versions), ecosystem, failure mode, and timeout. No output schema exists, so description sufficiently explains return values.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context that package accepts scoped names (e.g., '@types/node') and that version defaults to latest. This adds marginal value beyond the schema descriptions.

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

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

The description clearly states it performs a composite check for adding an npm package, combining deps.dev and bundlephobia. It specifies the resource (npm package) and action (scan), and distinguishes from siblings by noting NPM ecosystem scope and mentioning alternatives for other ecosystems.

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 mentions when to use: when an agent asks about safety, popularity, size, or cost of adding a package. It also notes that PyPI/Maven/Cargo/Go fall under deps.dev:version directly, providing alternatives. However, it does not explicitly state when not to use within the NPM ecosystem.

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 adds technical details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (truncated and flagged)'. 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?

Three sentences, front-loaded key purpose, efficient and no wasted words.

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

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

Given 3 parameters and no output schema, description covers purpose, behavior, limits, and pairing. Complete for agent use.

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

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

Schema description coverage is 100% (all parameters documented). Description adds default for limit (5) and query examples, but does not add meaning beyond 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?

Description clearly states 'Semantic search INSIDE a fetched record' and explains the use case (searching inside a large text, e.g., SEC filing). It distinguishes from sibling tool 'ask_pipeworx_grounded' by suggesting a pairing pattern.

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 the record is too big to cram into the prompt' and explains benefits (saves context, returns relevant passages). Does not provide explicit when-not-to-use, but context is clear.

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

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

Adds significant behavioral context beyond annotations: return value, account requirement, delivery channel behavior (always-on feed, email/SMS caps, webhook signing and auto-disable). Annotations already indicate non-read-only, non-destructive, idempotent, and open-world; description complements these well. Could explicitly mention idempotency behavior.

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

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

Single paragraph efficiently packs all critical information: purpose, prerequisites, types, delivery options, and return value. Every sentence adds value. Could be slightly restructured for readability but is not overly verbose.

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

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

Given the complexity (3 parameters, nested objects, multiple types, no output schema), the description covers input details, return value, prerequisites, delivery channels with limits and behavior, and how to consume the feed. Comprehensive for a create tool.

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

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

Schema coverage is 100%, and the description adds rich meaning: explains each subscription type with examples, describes delivery object fields (phone verification, email pattern, webhook expectations). Provides far more value than 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 the tool creates a 'proactive monitoring subscription to a live-data event stream' and returns a subscription ID. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

Provides clear context: requires a Pipeworx OAuth account, anonymous/BYO cannot persist. Lists supported subscription types with parameter examples. Does not explicitly mention when NOT to use this tool vs alternatives, but the prerequisites and type details guide appropriate use.

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

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

Annotations already declare safe, read-only, idempotent behavior. Description adds that it returns examples from live catalog, with category bucketing and exact tool+argument shapes. 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 relatively long but well-structured with synonyms, return explanation, and usage tips. Each sentence adds value; minor room for tightening.

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

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

Given low complexity (one optional param, no output schema) and many sibling tools, description thoroughly covers purpose and usage. Mentions meta-tools and distinguishes from alternative entry points.

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

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

Schema coverage is 100% with one optional parameter. Description adds value by listing possible topic values and explaining that omitting gives full spread. Adds semantic depth 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 explicitly states this is the onboarding entry point, lists synonym queries, explains returns category-bucketed example questions with tool+argument shapes, and distinguishes it as the first tool to use when unsure. Very specific verb and resource.

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

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

Clear guidance to use first when unfamiliar with Pipeworx, and explains when to pass a topic vs. no arguments. Does not explicitly exclude alternative tools but context implies primary use case.

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 that the row is deactivated (not deleted) and historical events remain, aligning with the annotation 'destructiveHint: false'. It also adds ownership enforcement, which is not in annotations. No contradictions.

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

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

The description is three sentences, front-loaded with the action and ID, and every sentence adds value 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?

Given one required parameter, existing annotations, and no output schema, the description fully covers the needed context: what it does, ownership, and effect on data.

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 provides a description for the 'id' parameter ('Subscription id (uuid) returned by subscribe'), so the description does not add further parameter semantics. Schema coverage is 100%, so baseline of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id', specifying a verb ('cancel') and resource ('subscription'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description provides context on ownership enforcement ('only cancel your own subscriptions') and the effect ('deactivated, not deleted'). However, it does not explicitly state when to use this tool versus alternatives like 'subscribe' or 'list_subscriptions'.

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 many behavioral traits beyond annotations: two distinct verification paths, the exact verdict set, the semantic distinction between could_not_verify and unsupported, citation format, and the fact that it replaces sequential calls. It also warns callers not to treat could_not_verify as evidence. This is rich context well beyond the readOnly/openWorld/idempotent hints.

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

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

The description is concise despite being information-dense. It front-loads trigger phrases, then states purpose, routing, return values, and caveats in a logical order. Every sentence adds value—no fluff, and the 'IMPORTANT for callers' section earns its place.

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

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

With no output schema, the description fully explains return values (verdict list, actual value, citation, reasoning) and the error semantics. It covers routing, edge cases, and performance benefits. For a tool of this complexity, the description is remarkably complete and self-contained.

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

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

Schema coverage is 100% for both parameters. The description adds extra context for tolerance_pct by explaining its role in hallucination detection and overriding the implied tolerance, which goes beyond the schema's basic definition. The claim parameter is well illustrated with examples. This surpasses the baseline of 3.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, with strong trigger examples and explicit scope. It distinguishes itself from siblings by focusing on verifying claims (not general research or entity comparisons) and even quantifies its efficiency benefit by replacing 4–6 sequential calls.

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

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

It states explicitly to use when the agent needs to check factual correctness of something a user said. It details routing logic (SEC EDGAR for company-financial claims, grounded pipeline for all others) and provides critical usage warnings about could_not_verify. It doesn't name alternative tools, but the context is clear enough; slightly less direct than an explicit 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.