Duffel

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds crucial details: cost implications (free Workers AI vs. BYO Anthropic), per-model return structure (score, confidence, signals, raw_response), and combined view. No contradictions with annotations.

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

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

The description is three sentences, each adding unique value. First sentence defines core function and scoring. Second explains model options and cost. Third lists use cases. No redundant or filler text.

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

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

Despite no output schema, the description explicitly states return fields (per-model score, confidence, signals, raw_response plus combined view). All 4 parameters are explained in schema and description. The tool's complexity is fully addressed.

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%, baseline 3. The description adds value by explaining default model, API key passthrough behavior, and the disambiguation role of 'context'. This justifies a 4.

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 ('probe') and resource ('LLMs') with clear outcome ('score visibility 0-100'). It explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. This differentiates it from sibling tools like 'ask_pipeworx' which are Q&A-based.

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 states when to use (visibility audits, brand checks) and provides context on model choice (free default vs. paid Anthropic). However, it does not explicitly mention when not to use or list alternative tools, though the sibling list implies distinct purposes.

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 and idempotentHint, and the description adds valuable context: returns structured answers with stable citation URIs, covers diverse data sources, and emphasizes it works on every tier with one fast call. No contradictions with annotations.

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

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

The description is longer than ideal but front-loaded with the key message 'PREFER OVER WEB SEARCH'. Each section adds value: sources, routing behavior, examples, alternatives. Structured with a clear escalation path, making it readable despite length.

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

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

For a complex tool with no output schema, the description covers return format (structured answer with citation URIs), scope, examples, and alternative tools. It could mention rate limits or response size, but overall it is sufficiently complete for the agent to invoke appropriately.

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

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

Schema coverage is 100% and already documents aliases (q, text, input, query, prompt) and provides examples. The description adds real-world example questions and clarifies natural language use, but most semantic weight is already in the schema, so baseline 3 applies.

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

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

The description clearly states the tool's function: it routes factual questions to the appropriate tool among 5,529 sources and returns structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

Provides explicit when-to-use guidance: 'START HERE for most questions' and lists trigger phrases like 'what is', 'look up', 'find'. Also gives clear escalation paths: use ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions, and mentions breaking news routing.

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

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

The description discloses behavioral details beyond annotations: it is a live experimental edge, may have candidate routing improvements active, currently has none active so it matches ask_pipeworx exactly, and 'falls back to nothing' (i.e., it is a fully working router, not a stub). Annotations already cover read-only/idempotent safety, so the description adds valuable experimental context without contradicting 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 concise at three sentences, with each sentence contributing meaningful information: beta identity, current status, and usage guidance. Slightly verbose with the specific date and tool count, but no wasted words overall.

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?

Though there is no output schema, the description explicitly references 'same response shape' as ask_pipeworx, which resolves ambiguity. It also provides current status, usage context, and comparison behavior, making it complete for a router tool with a single required parameter.

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

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

Schema coverage is 100% with each parameter (including aliases) described. The description adds only the phrase 'same arguments' which does not go beyond schema information. Baseline 3 is appropriate since the schema carries the 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 explicitly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. This clearly distinguishes it from the stable sibling ask_pipeworx and clarifies its experimental 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?

It gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. This tells the agent when to choose this beta over the stable alternative.

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

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

Despite annotations declaring readOnly and idempotent, the description adds rich behavioral context: it explains the success response shape, explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the extra LLM call cost. No contradiction with annotations.

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

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

The description is dense but every sentence carries value: purpose, mechanism, use cases, refusal criteria, cost tradeoff. It is front-loaded with the core value proposition and well-structured without redundancy.

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

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

Given the tool's complexity and no output schema, the description fully compensates by detailing both success and refusal return shapes, the extraction methodology, the single-question input, and cost versus value. It is complete for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% with all 6 parameters clearly documented as aliases for the same question string. The description adds no parameter-specific meaning beyond the schema's own descriptions, so baseline 3 applies.

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

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

The description explicitly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' with a distinct extraction step, distinguishing it from its sibling ask_pipeworx. It clearly names the verb (answer/returns), resource (Pipeworx tool results), and unique behavior (extracts using only tool result).

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

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

Provides explicit when-to-use context: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with specific examples. It also gives a when-not-to-use: 'prefer ask_pipeworx for casual lookups' and names the alternative.

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

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

The description discloses extensive behavioral details well beyond annotations: market matching confidence, resolution paths, cancellation rules, news fallback behavior, wide-spread handling, and blocking on low-confidence or closed markets. Annotations already indicate readOnly, openWorld, idempotent, and non-destructive, and the description adds context 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 long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It is front-loaded with the main purpose. Every sentence earns its place by providing critical context, but could be slightly more terse.

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 thoroughly explains the response structure: market fields, analysis block with edge calculations, evidence keyed by source, market_match_confidence with alternatives, parent_event for partitioned events, news fields with fallback info, and safety checks. This covers all essential aspects for an agent to use the tool correctly.

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

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

With 100% schema coverage, baseline is 3. The description adds significant meaning: explains the `market` parameter accepts slug, URL, or question text; describes `depth` enum values ('quick' vs 'thorough') and their implications; and clarifies `include_raw` default and when to set true. This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action (research), resource (Polymarket bet), and method (one call). It distinguishes from siblings like ask_pipeworx or polymarket_edges by focusing on a single bet and returning a structured evidence packet.

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

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

The description provides explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also covers when not to trust the analysis (low-confidence matches) and mentions alternative paths like closed markets. This gives clear guidance on 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?

Adds significant behavioral detail beyond annotations: handles off-calendar fiscal years correctly, sorts results by primary metric, returns paired data with citation URIs. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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

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

Single paragraph with no wasted words. Front-loaded with common user queries. Each sentence adds unique value (purpose, usage preference, parameter details, behavioral notes). Perfectly sized for its 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 (dual entity types, different data sources, sorting, citation URIs), the description covers all essential aspects. No output schema, but description adequately explains return format ('paired data + citation URIs'). Complete and self-sufficient.

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

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

Both parameters (type and values) are described in detail beyond schema: explains what each type pulls (revenue, net income for company; adverse events, FDA approvals for drug). Schema coverage is 100%, and description adds rich semantics for each field.

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

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

Description uses specific verbs like 'compare', 'side-by-side comparison', and concrete phrases ('which is bigger / better'). Clearly distinguishes from sibling tools by stating it replaces 8–15 sequential lookups, which differentiates it from single-entity tools like entity_profile.

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

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

Explicitly states to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear when-to-use directive. While not mentioning when not to use, the context is well-defined. Minor room to mention alternatives for non-comparison tasks.

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

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

The description discloses extensive behavioral traits beyond the annotations: decomposes questions, routes in parallel to 5,529 tools, returns findings with gaps[], never invents answers, produces resolvable pipeworx:// citations, includes hop fields and contradictions[], and semantically excerpts large records. It also covers latency expectations and account prerequisites. 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 long but information-dense; every sentence contributes unique value. It is front-loaded with the account requirement and alternative, but the extended single-paragraph structure with semicolons could be more scannable. Still, the density is justified given the tool's complexity.

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

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

With no output schema, the description fully covers the return contract: findings packet contents (evidence, confidence, source, fetched_at, citation), gaps[] for unanswered facets, contradictions[] for standard/thorough, and the behavior for unsupported topics. It also includes timing and hop iteration details, making it highly complete for a complex tool.

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

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

Schema coverage is 100% and both parameters are already well described in the schema. The description adds extra nuance by explaining the practical behavior of depth levels (gap recovery, lead-chasing, paid tier) and noting that broad/multi-part natural-language questions are acceptable, adding value beyond the schema.

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

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

The description clearly states the tool performs grounded multi-source research across 1,455 structured data sources in one call, and explicitly distinguishes it from sibling tools by noting this is not open-web search and contrasting with ask_pipeworx. The verb+resource+scope are all present and specific.

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

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

It provides explicit when-to-use and when-not-to-use guidance: best for broad/multi-part structured questions, single lookups should use ask_pipeworx, and breaking/current news should prefer ask_pipeworx because deep_research returns empty gaps. It also covers account tier requirements and the fallback alternative if not signed in.

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

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

Annotations already include readOnlyHint, idempotentHint, destructiveHint. The description adds significant behavioral context: it returns top-N most relevant tools with full schemas and curated examples, ready to call directly. This goes beyond what annotations provide and enhances transparency.

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

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

The description is informative and front-loaded with purpose. It efficiently covers usage, input, and output in a few sentences. While slightly verbose with example lists, every sentence adds value. Could be slightly more concise, 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?

The description fully explains what the tool does, when to use it, and what it returns (top-N tools with names, descriptions, full schemas, examples). No output schema exists, but the description compensates by detailing the return format. The context is complete for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description groups aliases for the query parameter but adds no new semantic meaning beyond what the schema provides. The description focuses on overall tool behavior rather than parameter specifics.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example tasks and data sources, making the functionality explicit. It distinguishes itself from sibling tools by being the discovery tool that helps navigate the toolset.

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: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also describes scenarios like browsing, searching, or looking up tools, which is precise and directive.

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 a safe, idempotent read operation (readOnlyHint, idempotentHint, destructiveHint). The description adds value by specifying that the tool returns exactly the 5 cheapest offers from the Duffel Flights API, that it uses real inventory accessible via a token, and that a test token works for sandbox. No contradictions with annotations.

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

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

The description is compact yet comprehensive: a single sentence conveys the main action, then key details about the result, and a concrete example. Every sentence is necessary and well-structured. The front-loading of the purpose is effective.

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

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

Despite no output schema, the description thoroughly explains what the tool returns (total price, airline, per-segment flight numbers/times) and that it returns 5 cheapest offers. All 7 parameters are documented in the schema, and the description clarifies the real-world data source. The example demonstrates usage with typical parameters.

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

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

Schema description coverage is 100%, and the schema already explains all parameters clearly. The description adds minimal semantic value beyond the schema, except for the example showing a full invocation. Baseline is 3 for high coverage; the example slightly raises value but not enough for a 4.

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 searches flights with pricing, specifying the return of the 5 cheapest real offers along with total price, airline, per-segment flight details. The verb 'Search' combined with the resource 'flights' and scope definition ('real, bookable') makes the tool's purpose unmistakable. No sibling tool competes for this functionality.

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 (to find real flight inventory) and includes an example with a test token for sandbox usage. It does not explicitly state when not to use, but the sibling list contains no similar tools, so the context is sufficient. The mention of real vs sandbox data provides clear context for testing.

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

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

The description adds significant behavioral context beyond annotations: it fans out across multiple sources, specifies return fields (cik, filings, fundamentals, patents with sunset date, news fallback, LEI), and notes patents API soft-fails. Annotations already indicate read-only and idempotent, and description aligns.

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: starts with example queries, then usage preference, then lists returns. Every sentence adds value, though slightly verbose. Front-loading with examples is effective.

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

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

With no output schema, the description thoroughly explains return values (cik, filings with URIs, fundamentals sorted, patents with limitation, news, LEI). It covers all expected outputs and limitations, making the tool fully understandable.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra context: type only supports 'company', value must be ticker or zero-padded CIK, and names are not supported. This enhances understanding beyond 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's purpose: generating a full cross-source profile of a US public company. Example queries like 'Tell me about X' and 'company profile for Microsoft' illustrate usage. It distinguishes from siblings like compare_entities and deep_research by emphasizing holistic view.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and indicates when to use (holistic view) and when not (if only have a name, use resolve_entity first). This provides clear 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 destructiveHint=true and idempotentHint=true. The description adds the verb 'Delete' and context for use, but does not elaborate on behavior beyond what annotations provide, such as handling of non-existent keys.

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

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

Two concise sentences; the first states the core action, the second provides usage guidance. No redundant information, well front-loaded.

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

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

For a simple destructive tool with one parameter and comprehensive annotations, the description covers purpose, usage, and pairing adequately. No output schema is needed.

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

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

Schema coverage is 100% and the description does not add extra meaning for the 'key' parameter beyond what the schema already provides (e.g., format, naming conventions). Baseline of 3 applies.

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

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

The description clearly states the action 'Delete a previously stored memory by key' and provides specific use cases. It also mentions pairing with sibling tools 'remember' and 'recall', distinguishing it from alternatives.

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 (stale context, task done, clear sensitive data) and suggests pairing with remember and recall, but does not provide 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?

The description explains that it fetches the page, extracts content, and emits a markdown blob, adding behavioral context beyond the annotations (readOnly, openWorld, idempotent). No contradictions.

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

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

The description is moderately concise with four lines, front-loading the core action. Each sentence adds value, but some redundancy (e.g., 'ld' from context) could be trimmed.

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

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

Given no output schema, the description fully describes the output format and usage. It covers both parameters, output format, and intended audience, making the tool 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 (url, max_links), and the description does not add significant new meaning beyond what the schema provides (e.g., it restates 'Full URL' and 'Maximum number of link entries').

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

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

The description clearly states it generates an llms.txt file for any URL, specifying it extracts title/description/key links and outputs standard markdown. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on the llms.txt format.

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 three explicit use cases (client indexing, personal project, competitor audit), providing clear context. It lacks explicit when-not-to-use or alternative tools, but the use cases are sufficient.

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

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

Annotations already declare readOnlyHint=true, but description adds return fields and optional parameter. No contradictions.

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

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

Two sentences with no waste: first sentence defines purpose and return fields, second provides usage guidance.

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

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

For a simple list tool with one boolean parameter, description covers purpose, usage, and return fields. Annotations cover safety. 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%. Description does not add meaning beyond schema's parameter description, so baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' and enumerates return fields. Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel', implying 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?

Discloses key behaviors beyond annotations: returns claim_token when no account, is rate-limited, free, doesn't count against quota, team reads digests daily, and signals affect roadmap. No contradiction with annotations, which are all false.

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

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

The description is front-loaded with the core purpose and then provides dense, actionable guidance. It is longer than average, but each sentence earns its place; a slight trim would improve scannability without losing essential details.

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

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

Despite no output schema, the description explains what to expect (claim_token for anonymous filing), how to use it later, and the tool's non-quota nature. It fully covers scope, exclusions, and post-submission behavior, making it complete for the tool's complexity.

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

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

Although the schema already covers all parameters at 100%, the description adds significant meaning: it gives an example for claim_token usage, clarifies that feedback should reference Pipeworx tools/packs, and advises against pasting user prompts. This enriches parameter understanding beyond schema descriptions.

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

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

The description clearly states the tool's purpose: telling the Pipeworx team something is broken, missing, or needs to exist. It distinguishes from siblings by limiting scope to tools served by this Pipeworx connection and explicitly excluding other MCP servers.

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

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

Provides explicit when-to-use guidance (bug, feature, data_gap, praise) and when-not-to (different MCP server). Also explains claim_token usage for follow-up, rate limits, and daily digest review, offering clear direction on how and when to invoke the tool.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds source (CF analytics-engine), no PII, caching behavior (5min-1h), and data format (pack, tool, count), providing useful behavioral context 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?

Description is concise (5 sentences), front-loaded with purpose, and every sentence provides essential information about returns, use cases, source, and caching. No redundant or missing elements.

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

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

Despite no output schema, the description explains return types (top tools, top packs, total call volume) and data structure. Caching behavior is noted. Minimal gaps for a simple trending tool, though pagination or result limits are not mentioned.

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 description on the only parameter. The description enriches by explaining window semantics (short vs long windows surface hot vs steady-state demand), adding value beyond the enum description.

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

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

The description clearly states the tool returns trending tools/packs and call volume over a window, using specific verbs and resources. It distinguishes itself by focusing on aggregate agent usage rather than individual queries, though explicit sibling differentiation is absent.

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 concrete use cases are provided (discovering hot data sources, confirming canonical choice, checking alignment). Use context is clear, but no explicit when-not-to-use or alternatives are mentioned.

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

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

The description adds extensive behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint): it explains internal logic (monotonicity, partition-sum checks, Jaccard similarity filter, partition filter, fill check) and response structure. No contradictions with annotations.

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

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

The description is front-loaded with a concise summary and well-organized into sections (modes, semantic anchor, partition filter, response, fill check). While lengthy, every sentence adds value given the tool's complexity; minor verbosity (e.g., exact thresholds) could be trimmed but does not detract significantly.

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 documents the response format (opportunities[] with fields, partition_check structure) and explains the fill check logic. It covers all aspects needed for an agent to decide when and how to use the tool, including constraints and edge cases.

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

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

Schema description coverage is 100%, and the description adds significant meaning beyond the schema: it clarifies that event accepts full Polymarket URLs, explains how topic triggers cross-event scanning with semantic matching, and details the behavior differences between modes.

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 and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing specifically on arbitrage scanning with multiple scan modes.

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

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

The description explicitly states when to use each mode ('Call with NO args for a trending_scan... pass event for... pass topic for...'), gives recommendations ('event recommended for a specific market'), and mentions when not to trade (realizable_edge_pp <= 0). It also references an alternative tool for custom sizing (polymarket_fill_risk).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds significant behavioral context: caching (1h at KV level), response structure with diagnostics, model family details, slippage handling, edge net of slippage, 24h-move warning, and tradeable-edge filters. 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 densely packed with technical details, which is informative but could be more structured or concise. It front-loads purpose but then dives deep into model families, formula details, and response fields, making it long.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is very complete. It explains response structure (segments, diagnostics), caching, and all key fields. Compensates for missing output schema by detailing what each opportunity contains.

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 has a description. The tool description adds extra meaning, e.g., explaining min_kelly vs min_partition_leg_kelly, tradeable-edge knobs, and how parameters affect segments. This goes beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, positioning it as a daily betting research tool. It distinguishes from siblings like polymarket_arbitrage by detailing unique model families and segments.

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?

Extensive guidance on when to use (discovering opportunities) and how to filter results via knobs (min_liquidity, max_spread_pp). Includes fed_candidates exclusion note. Missing explicit mention of when not to use or alternatives among siblings, but context makes it clear.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: snapshot TTL limits, computation methods (daily closes, not intraday), and data gap conditions. No contradiction.

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

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

The description is well-organized with sections (RESPONSE, LIMITS) and front-loaded with the key question. Slightly long but all sentences add value; could be more terse in describing response fields.

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 details the response structure (tracked[], expired[], snapshot_dates[]) including field meanings. Covers all aspects needed for usage.

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

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

Schema coverage is 100%, but the description adds meaning: default values, clamps for days, and interpretation of window families. Slightly exceeds baseline.

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

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

The description clearly states the verb ('answers') and resource ('edge persistence and decay telemetry'), with specific outputs. It distinguishes itself from sibling tools like polymarket_edges by focusing on history and decay.

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 the use case (differentiating fresh vs old edges) and provides default values for parameters. However, it does not explicitly contrast with alternative tools or state when not to use it.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds operational behavior: walking the ladder, returning specific fields like top_of_book, vwap_fill_price, slippage_pp, and warning about thin books and forced directional risk. 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 long but well-organized with clear sections for single-market and basket modes, using bold for key terms. Some sentences are dense; could be slightly more structured with bullet points, but overall efficient given the detail.

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 (two modes, multiple parameters, no output schema), the description is very complete. It explains both modes, provides defaults, gives context for when to use, and details return fields. Compensates well for lack of output schema.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains size_usd differs for single-market vs. basket, side default behavior for baskets, and usage constraints (requires one of market or event). Goes beyond the schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It is specific about what it returns and differentiates from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial fills cause directional risk). Provides clear context for when to use vs. alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. Description adds detailed behavioral context: compatibility_warning conditions, temporal_alignment impact, and skipped_cross_type/subtype counters. No contradiction with annotations.

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

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

Description is thorough but not overly verbose; front-loaded with purpose and modes. Every sentence adds value given the complexity. Could be slightly more structured with bullet points, but remains clear and efficient.

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

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

Despite no output schema, the description thoroughly explains response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, counters). Covers edge cases and behavior for each scenario, making the tool 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 covers all 3 parameters with descriptions. Description adds significant meaning beyond schema: explains topic macros, how explicit tickers override, and how parameters interact (e.g., 'topic auto-fetches matching event on each venue'). Provides example values for explicit fields.

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

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

Description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket, specifies two modes (topic shortcuts and explicit tickers), and explains what the response contains. Distinguished from sibling tools like polymarket_arbitrage by focusing on inter-venue 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 guidance on when to use (compare same outcome across venues) and when not to (e.g., compatibility_warning indicates no arbitrage). Warns that most pre-mapped topics may not be tradeable, setting realistic expectations.

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. The description adds useful context about scoping to an identifier (anonymous IP, key hash, account ID) and pairing with remember/forget, which goes beyond what annotations provide.

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

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

Two sentences, front-loaded with purpose, no fluff. 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?

For a simple read tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and relationships to sibling tools. No gaps.

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

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

Schema coverage is 100%, and the description explains the behavior of the optional key parameter: omit to list all keys, include to retrieve a specific value. This reinforces the schema and adds clarity.

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

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

The description clearly states the verb (retrieve/list) and resource (saved values/keys), and distinguishes from siblings like 'remember' and 'forget' by explicitly naming them. It also gives concrete examples of what can be retrieved.

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 context on when to use the tool (look up stored context) and mentions scoping to an identifier. However, it does not explicitly state when not to use it or list alternatives, though sibling tools are available.

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

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

The description states that setting 'mark_read:true' flags events as read and affects future calls, indicating a side effect. This contradicts the annotation 'readOnlyHint: true', which asserts no side effects. According to scoring rules, score 1 for contradiction.

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

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

The description is well-structured with distinct sentences for purpose, return data, parameters, and additional usage. It is reasonably concise, though the last sentence about the REST endpoint could be considered extra.

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

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

The description explains return structure and provides external access method. It covers most usage aspects but omits details on 'unread_only' parameter and how 'read' state is managed. With no output schema, more detail would be beneficial.

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

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

All 5 parameters are described in the input schema (100% coverage), so baseline is 3. The description adds examples for 'type' and 'since' and explains 'mark_read', but does not mention 'limit' or 'unread_only'. Value added is marginal.

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

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

The description clearly states it pulls fired events from a subscription feed and returns recent alerts. It specifies the resource (subscription feed) and action (pull/return). However, it does not explicitly distinguish from sibling tools like 'recall' or 'recent_changes', which could also retrieve recent data.

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

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

The description mentions polling works fine and provides an alternative REST endpoint for scripts/dashboards. It does not, however, give explicit guidance on when to use this tool versus its siblings or when not to use it.

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

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

The description discloses detailed behavioral traits beyond the annotations: it fans out to SEC EDGAR, GDELT with GNews fallback, and USPTO (with soft-fail note). It explains the parallel call nature, the return format, and the citation URIs. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is dense but well-structured: it opens with example queries, then explains the fan-out, parameter specifics, return format, and sibling distinction. Every sentence serves a purpose; however, it is slightly verbose for the 'what's new' examples, which could be condensed. Still, it maintains a logical flow.

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 (multiple data sources, fallback logic, soft-fail, date formats, return structure), the description covers all essential aspects. No output schema exists, but the description explicitly lists the returned fields (changes grouped by source, total_changes, citation URIs), making the tool self-contained for invocation.

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

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

Although the schema already has 100% coverage with good descriptions, the tool description adds extra value: it provides typical usage examples for 'since' (e.g., 'Use "30d" or "1m" for typical monitoring') and confirms that 'type' only supports 'company'. The description enhances the semantic understanding beyond the schema alone.

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

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

The description is exceptionally clear, starting with example user queries ('What's new with X', 'latest on Y') and then stating the tool's purpose: a change feed for a company in a recent window. It explicitly distinguishes itself from the sibling 'entity_profile' tool by specifying when to use each, providing strong purpose clarity.

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 with real queries and examples. It also clearly states when not to use this tool: 'Use entity_profile instead when you want the static profile'. This directly helps the agent decide between siblings.

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

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

Annotations already indicate idempotentHint=true (safe to repeat) and non-destructive, so the description adds value by explaining scoping by identifier, persistence differences (authenticated vs anonymous), and pairing with recall/forget. No contradiction; behavior is well-covered.

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

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

Three concise sentences: purpose, guidance, and mechanics. Every sentence adds new, non-redundant information. No filler.

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

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

For a simple two-parameter write tool with no output schema, the description covers purpose, usage, persistence behavior, and sibling relationships comprehensively.

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 for key and value. The tool description adds extra context like scoping by identifier and use-case examples, raising it above the baseline 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 saves data for reuse across conversations/sessions, with specific examples (resolved ticker, target address, user preference, research subject). It distinguishes from sibling tools recall and forget by framing them as companion 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?

The description explicitly says when to use ('when you discover something worth carrying forward') and pairs with recall/forget for retrieval and deletion. It lacks an explicit 'do not use when' clause but strong contextual signals make selection straightforward.

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 readOnly/idempotent annotations, the description discloses that the tool cascades through multiple internal lookup endpoints, that LEI/FIGI enrichment degrades gracefully (EDGAR identifiers still return even if GLEIF/OpenFIGI fail), and that unresolvable identifiers are explicitly listed under `unresolved` rather than omitted. These are valuable behavioral insights not captured by the annotations.

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

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

The description is long but well-structured: it front-loads example user queries, then states the core purpose, SUPPORTED TYPES, and key behaviors. Every sentence provides value—no fluff. The use of quotes and labeled sections makes it easy to scan.

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

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

With no output schema, the description must explain return values, and it does thoroughly: identifiers, source labels, unresolved handling, and degradation behavior. It also connects the tool to its role in the broader tool ecosystem ('other tools require as input'), making it complete for a complex tool.

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

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

Schema coverage is 100% (both 'type' and 'value' have descriptions). The description adds context for what each type returns (CIK, LEI, FIGI for company; RxCUI, ingredient, brand for drug) but does not introduce new parameter constraints or formats beyond the schema examples. Baseline 3 applies because the schema already documents parameters well.

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 resolves user-spoken names to canonical/official identifiers (CIK, LEI, FIGI, RxCUI). It opens with concrete example queries and explicitly says it provides identifiers other tools require as input, distinguishing it from sibling tools like entity_profile or validate_claim.

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: 'Use FIRST whenever you have a name but need an ID.' It also explains that each call replaces 2-3 manual lookups, reinforcing its primary use case. It does not explicitly mention when not to use it or name alternative tools, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds valuable context that it probes each entity and returns score, confidence, signal density, which is sufficient for understanding 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?

The description is three sentences, front-loaded with the action verb 'Compare', and every sentence adds essential information. No unnecessary words or redundancy.

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

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

Given the tool's complexity (4 parameters, no nested objects, no output schema), the description covers the purpose, inputs, output format, and internal mechanism (using ai_visibility_check). It is complete for an agent to understand when and how to use it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by noting that the first entity is treated as the subject for narrative, models default to workers-ai, and context disambiguates common names. This goes beyond the schema alone.

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

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

The description clearly states that the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. It explicitly differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on AI presence.

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

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

The description provides a clear use case (competitive AI-marketing audits) and implies when to use this over ai_visibility_check (multiple entities). It could be improved by explicitly stating when not to use it or mentioning alternatives, but it still offers solid 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?

Despite comprehensive annotations (readOnlyHint, etc.), the description adds significant behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s and may time out, and the sources_failed field will list it. This goes beyond the annotations' binary 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 densely packed but front-loaded with purpose. Each sentence adds distinct information (purpose, usage, returns, limitations, ecosystem scope, error behavior). While lengthy, it is efficient and well-organized, earning a high score.

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 check, multiple sources, partial failures), the description is remarkably complete. It covers inputs, outputs (summary block, per-advisory, links, alternatives), error handling, and ecosystem restrictions. No output schema exists, but the description lists return fields explicitly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by clarifying that scoped packages (like @types/node) are accepted and that version defaults to latest when omitted. This extra context justifies a score above baseline.

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

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

The description clearly states the tool's purpose: a composite check for npm packages (license, advisories, version history, bundle size, ESM/tree-shake). It uses specific verbs ('scan', 'fans out across') and resource identifiers, distinguishing it from sibling tools that focus on different domains.

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: 'whenever an agent asks is X safe / popular / small' or 'what does adding lodash cost me'. It also provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding the agent to alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds specific technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K character cap with truncation and flagging, and output includes character offsets and similarity scores. No contradictions.

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

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

The description is a single dense paragraph, front-loaded with the core action. Every sentence adds unique value: use case, companion tool, technical specifics. No redundant 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?

Without an output schema, the description explains return values (passages with offsets and similarity scores) and constraints (200K cap, truncation flag). For a search tool, this covers all necessary context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the 'text' parameter as a fetched record, providing examples for 'query' (e.g., 'supply-chain risk'), and implying 'limit' via 'top-N passages'. It enhances understanding beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, with concrete examples like SEC 10-K or articles. It distinguishes itself from sibling tools by naming ask_pipeworx_grounded and explaining how they pair together, avoiding 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 explicitly says when to use: 'when the record is too big to cram into the prompt.' It pairs with ask_pipeworx_grounded, giving a practical workflow. However, it does not explicitly list when not to use or name alternatives beyond the paired tool, leaving some implicit 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?

Discloses required OAuth account, delivery channel specifics, SMS cap of 10/day, and webhook auto-disable after 10 consecutive failures. Annotations indicate idempotentHint=true and readOnlyHint=false, and description does not contradict; it adds substantial 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?

Well-structured with clear sections for types and delivery, but slightly lengthy. Could be trimmed without losing clarity.

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

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

Covers all aspects: creation, types, parameters, delivery channels, limits, and webhook verification. No output schema, but description is sufficient for an agent to use correctly.

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

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

Despite 100% schema coverage, the description adds rich examples and constraints for each type (e.g., items codes, topics, series_id), and details delivery channel requirements (verified phone, webhook signing secret).

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

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

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream', providing a specific verb and resource. It distinguishes from siblings 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?

Explicitly mentions requirement of Pipeworx OAuth account and gives examples for each subscription type with parameters. However, it does not explicitly state when not to use or compare to alternatives.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds useful behavioral context: it returns example questions with exact tool+argument shapes, drawn from the live catalog, and can be called with no arguments or a topic. No contradictions with annotations.

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

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

The description is dense but well-organized, front-loading example queries and purpose. Every sentence adds value, though the list of categories could be considered somewhat lengthy. It earns its space without being 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?

Despite no output schema, the description completely explains what the tool returns (category-bucketed example questions with tool+argument shapes). It covers parameter usage, context of use, and differentiates from siblings. Sufficient for effective agent invocation.

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

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

The only parameter 'topic' is described in both the schema and the description. The description adds value by providing concrete examples ('finance', 'pharma', 'betting') and explaining that omitting it gives a full spread. Schema coverage is 100%, so baseline 3, plus extra context justifies 4.

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: it returns category-bucketed example questions and tool suggestions for onboarding. It lists exact user queries it answers and distinguishes it from other meta-tools like ask_pipeworx.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. While it doesn't explicitly state when not to use, the context of onboarding 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?

Beyond annotations (destructiveHint=false, idempotentHint=true), the description reveals that the row is deactivated (not deleted) and ownership is enforced, adding significant 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?

Two concise sentences with front-loaded purpose. No fluff; 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?

Covers action, constraint, and outcome (deactivated, history preserved). Lacks return value specification, but given tool simplicity and annotations, it's nearly 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 already fully describes the id parameter (type, purpose). The description adds ownership context (id must belong to caller) but no further syntax or format details.

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 cancels a subscription by ID, with ownership enforcement. It distinguishes from sibling tools like subscribe and list_subscriptions by specifying the action and constraints.

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 ownership enforcement (only own subscriptions) and that deactivation preserves history for recent_alerts, providing clear when-to-use and context about side effects.

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

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

The description goes far beyond the annotations, explaining the verdict set, the meaning of could_not_verify (with verification_error), the unsupported verdict, and the automatic routing behavior. It also warns callers about misinterpreting could_not_verify. This is rich behavioral context fully complementing 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 dense but highly structured, starting with concrete examples, then explaining the routing, return verdicts, and an important caller note. Every sentence earns its place, and the 'IMPORTANT' section is clearly flagged. No wasted words.

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

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

Despite having no output schema, the description fully explains return values (verdicts, actual value, citation, reasoning) and error semantics. It also provides routing logic and explicitly states what 'unsupported' means. For a tool with this complexity, the description is complete.

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

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

Schema coverage is 100% and both parameters are thoroughly described in the schema (including examples, defaults, and usage for tolerance_pct). The description itself adds no parameter-specific semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific query examples. It distinguishes itself from sibling tools by focusing on fact-checking and explicitly noting it replaces 4-6 sequential calls, making its scope unambiguous.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing context (financial claims vs. other claims). However, it does not explicitly mention when not to use or name alternative tools, so it doesn't fully meet the 'when-not/alternatives' criterion.

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