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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it routes internally across thousands of tools, auto-fills arguments, returns structured answers with stable citation URIs, and describes the one-call default behavior. It does not contradict the annotations.

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

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

The description is long, but the tool is a high-complexity default router, so the length is largely justified. It front-loads the key directive ('PREFER OVER WEB SEARCH') and organizes guidance into trigger phrases, examples, and escalation rules. A few phrases are slightly redundant — such as 'START HERE for most questions' and 'works on every tier, one fast call' — but they reinforce rather than distract.

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 breadth, the description is unusually complete: it enumerates domains, trigger phrases, example queries, default behavior, output format with citations, and explicit guidance on when to step up to more specialized siblings. There is no output schema, but the description adequately explains what the agent should expect in return. An agent has everything needed to decide when and how to call this tool.

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

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

Schema description coverage is 100%, so the schema documents the `question` parameter and its aliases thoroughly, including examples. The description adds that the tool 'fills arguments' internally, but it does not need to repeat parameter details. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description clearly states a specific function: route natural-language questions to one of 5,724 tools across 1,497 sources and return structured answers with pipeworx:// citation URIs. It also distinguishes itself from ask_pipeworx_grounded and deep_research by naming when those alternatives should be used. An agent can immediately tell what this tool does and how it differs from siblings.

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

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

The description is explicit about when to use the tool: prefer it over web search for factual questions, start here for most questions, and use it even when web search could answer. It also gives clear escalation criteria — ask_pipeworx_grounded for a hallucination-resistant single answer, deep_research for broad/multi-part questions — plus concrete example queries. This leaves no ambiguity about tool selection.

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

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

Annotations already declare read-only and non-destructive behavior; the description adds meaningful context about live candidate routing, the absence of an active candidate, and that it is a complete working router rather than a fallback. 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 efficient, with the core purpose, current behavior, and usage instruction front-loaded. The retirement date is a small extra detail but helps explain the current exact-match state.

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

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

For a tool with no output schema, it doesn't spell out the response format, but it explicitly ties the response shape to ask_pipeworx, making it inferable. It covers current status, fallback behavior, and the relationship to the stable router, leaving only a minor gap.

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

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

The input schema already documents question and its five aliases with 100% coverage, so the description doesn't need to explain parameters in detail. It adds no new parameter-level semantics, but the schema carries the weight.

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

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

Clearly identifies as a beta variant of ask_pipeworx, a universal router with the same 5,724 tools, arguments, and response shape. It distinguishes itself by enabling candidate routing improvements live under test, and notes that it currently matches ask_pipeworx exactly.

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

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

Explicitly instructs to use it exactly like ask_pipeworx when the newest routing is desired, and positions it as the experimental edge compared to the stable router. It does not spell out when to avoid it, but the selection context is clear enough.

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 substantial behavior beyond the annotations: it explains the internal routing ('picks the right tool from 5,724 across 1497 sources, fills arguments, fetches the data'), the extraction restriction ('using ONLY what the tool result contains'), the exact success/refusal response shapes with refusal_reason values, and the extra-cost caveat. No contradiction with annotations exists.

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 average but every sentence earns its place: core behavior, routing, output contract, refusal contract, use-cases, exclusions, and cost. It is front-loaded with the defining trait and structured so an agent can quickly decide whether to invoke it.

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 specifies the return shape on both success and refusal, including refusal_reason enumerations. It also explains the relationship to a heavily used sibling and the cost-vs-fidelity tradeoff, leaving an agent with all information needed to call it correctly.

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

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

The input schema documents all 6 parameters (question plus five aliases) with descriptions, so coverage is 100%. The description does not need to repeat parameter details; it only implicitly references the natural-language question. It meets the baseline since the schema already carries the full semantic load.

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

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

The description opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads', making the tool's grounded/refusal-oriented behavior immediately clear. It then distinguishes itself from ask_pipeworx by naming the sibling and explaining the same routing but added extraction step.

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

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

The description explicitly states when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'. It also gives a clear exclusion: 'prefer ask_pipeworx for casual lookups', and notes the cost tradeoff of 'one extra LLM call vs ask_pipeworx'.

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

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

The description 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?

Beyond the read-only/idempotent/non-destructive annotations, the description discloses substantial behavior: the decomposition and parallel routing to 5,724 tools, the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), the explicit gaps[] behavior with 'never invented', hop fields, resolvable citation_uri, contradictions[] for standard/thorough, semantic excerpting rather than head-truncation, account/tier constraints, and latency expectations. This far exceeds what annotations provide.

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

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

The description is long but almost every sentence carries operational value, and it is front-loaded with the most critical constraint ('ACCOUNT REQUIRED... If you are not signed in, use ask_pipeworx'). It loses a point for mild redundancy — 'thorough needs a paid plan' is stated twice, and 'NOT open-web search' is emphasized repeatedly — which slightly dilutes the structure.

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

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

With no output schema, the description takes on the burden of explaining the return value, and it does so thoroughly: findings packet, gaps[], contradictions[], hop fields, and resolvable citation_uri. It also covers account/tier prerequisites, latency, depth semantics, and explicit routing to alternatives, making it 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 description coverage is 100%, so the baseline is 3. The description goes further by adding semantics the schema does not fully capture: depth:'thorough' requires a paid plan, 'standard' re-angles unanswered gaps, 'thorough' chases leads, and latency varies by depth. The question parameter is also enriched with 'broad/multi-part is fine — decomposition is the point.'

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources... in ONE call.' It clearly distinguishes itself from siblings by explicitly saying 'this is NOT open-web search' and contrasting with ask_pipeworx, so an agent can tell it apart without opening the schema.

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

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

Usage guidance is explicit and actionable: it says to use for 'broad/multi-part questions over structured data', to use ask_pipeworx 'for a single lookup' and for breaking/current-news topics, and even provides the sign-in fallback ('If you are not signed in, use ask_pipeworx instead'). Both positive and negative selection criteria are spelled out.

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 declare readOnlyHint=true and destructiveHint=false, and the description is fully consistent with that — it is a purely analytical read tool. Beyond annotations, it richly discloses behavior: safety fields (compatibility_warning/codes[]), the fee disclaimer (gross not net), matching methodology (keyword/word overlap, not shared resolution source), skipped-pair counters, and the temporal_alignment null semantics. Extraordinary disclosure depth.

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 exceptionally long and dense, with safety-code details, counters, and fee notes packed into a single paragraph. It is front-loaded with the core purpose, which is correct, but the density makes it hard for an agent to parse quickly. Genuinely valuable content, yet it could be restructured into clearer sections or tightened.

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

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

This is a complex tool with 3 optional params, two modes, and a rich safety-field surface, and with no output schema, the description must carry the return-format burden. It covers response fields (top_spreads_pp, fees_note, compatibility fields), all codes, the temporal_alignment null meaning, and skipped counters. Nothing an agent needs to call and interpret this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by explaining the topic→event mapping, the override semantics ('Overrides the topic-mapped Kalshi side'), and that both modes share the same matcher and disclosures. This goes beyond what the raw schema provides.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly locates the tool against siblings like polymarket_arbitrage and polymarket_edges that operate on single venues. The purpose is unambiguous and differentiated.

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

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

The description explains TWO explicit modes (topic shortcuts vs explicit ticker/slug), how both run the identical matcher, and gives honest guidance that 'pre-mapped ≠ tradeable' and that most topics return compatibility_warning today. It does not name an explicit alternative tool to route to when this one isn't right, and could state when to prefer polymarket_arbitrage, but the mode-selection guidance is strong.

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?

Annotations already mark the tool as read-only, idempotent, and non-destructive, but the description adds substantial behavior beyond that: enrichment degrades gracefully when GLEIF or OpenFIGI is unavailable, ambiguous matches return `figi_candidates` rather than asserting, unresolved identifiers are explicitly surfaced under `unresolved`, and each call cascades through several lookup endpoints.

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

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

The description is dense but every clause earns its place: trigger examples, selection rule, supported types, source behaviors, and failure-mode caveats. It is front-loaded with user phrasings and the 'Use FIRST' directive, and it is appropriately sized for the tool's complexity.

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

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

For a two-parameter tool with no output schema, the description fully explains what is returned (canonical identifiers with source labels, `unresolved`, `figi_candidates`), how failures degrade, and the exact format expectations for inputs. Combined with the rich annotations, nothing needed to call this tool correctly is missing.

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

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

Although schema coverage is 100%, the description adds meaningful semantics for both parameters: it expands what each `type` value actually does, gives concrete accepted values for `value` (e.g., 'AAPL', '0000320193'), and warns against passing full noun phrases for bonds because trailing security-class words match nothing. 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 states a clear verb-resource pair: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It enumerates concrete trigger phrasings and distinguishes the two supported entity types, company and drug, and points to 'Use FIRST whenever you have a name but need an ID,' making its role distinct from sibling tools.

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

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

The description gives an explicit usage rule ('Use FIRST whenever you have a name but need an ID') and details acceptable inputs, including ticker, CIK, ISIN, company name, and brand/generic drug names. It provides strong context, but it does not explicitly name alternatives or state when not to use this tool versus sibling tools like entity_profile.

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

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

Annotations already declare 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.