Cactus

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond annotations: calling Anthropic incurs direct costs (BYO key), the default is free Workers AI, and the return shape (per-model {score, confidence, signals, raw_response} + combined view). This extra detail about external calls and cost is useful.

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: first sentence states the core purpose and output, second provides model/cost details, third lists use cases. Every sentence adds distinct value with no redundancy, and the most important information is front-loaded.

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

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

Given the tool's moderate complexity (4 params, 1 required, no enums) and rich annotations, the description covers the essential aspects: purpose, default behavior, cost implications, return values, and use cases. While there is no output schema, the description explicitly lists the return structure, which compensates. Minor gaps like pagination or error handling are not critical for this read-only tool.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds meaning beyond the schema by explaining the free default model (workers-ai), that `_apiKey` enables Anthropic probing with direct payment, and that `context` helps disambiguate. This clarifies defaults and the purpose of `_apiKey` beyond its schema description.

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

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

The description uses a specific verb ('Probe') and resource ('one or more LLMs for what they know about a business/brand/product/topic') and clearly distinguishes from siblings by focusing on visibility scoring (0-100) per model. It also differentiates from similar tools like 'scan_competitor_ai_presence' by emphasizing multi-model probing and quantitative scoring.

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

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

The description explicitly names use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring', providing clear context for when to use. It also explains the default model and optional Anthropic probing, giving practical guidance on invocation, but it does not explicitly mention when not to use it or name alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety profile is covered. The description adds valuable behavioral context: it routes through 5,358 tools, fills arguments automatically, and returns structured answers with pipeworx:// citation URIs. It doesn't mention potential latency or data freshness, but the added detail goes beyond the annotations.

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

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

The description is long but every sentence earns its place: it opens with a strong directive, enumerates use cases, gives examples, and contrasts with alternatives. The structure front-loads the most critical 'PREFER OVER WEB SEARCH' guidance and flows logically into when to escalate.

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 (routing across thousands of sources) and lack of an output schema, the description is remarkably complete. It covers default entry point, applicable domains, example queries, return format (structured answer with citations), and clear branching to sibling tools for specialized needs. This equips an agent to decide correctly without additional context.

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

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

Schema coverage is 100% with six parameters all documented as aliases for 'question'. The description reinforces this by explicitly listing the accepted aliases and providing natural-language examples in the schema. It adds clarity that all parameters funnel to one core input, which is helpful beyond the schema's individual 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 answers factual questions about real-world data across many domains, routes to 5,358 tools, and returns cited answers. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different needs.

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 'PREFER OVER WEB SEARCH', 'START HERE', and provides concrete examples of when to use it. It also gives clear step-up guidance: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, making the choice between tools explicit.

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 cover safety (readOnly, idempotent, non-destructive). The description adds valuable context: currently no candidate is active, so it matches ask_pipeworx exactly; it 'falls back to nothing' (i.e., it is a full router, not a stub); and results are compared against the stable router for merge decisions. This beyond-annotation detail helps calibrate expectations.

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 four sentences and front-loads the core purpose ('identical universal router') before explaining the experimental nature. It is somewhat verbose with repeated mentions of 'same' and 'identical', but each sentence adds context about behavior, usage, and current state. It earns a 4 for being informative without excessive padding.

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 moderate complexity (single question parameter, annotations, no output schema), the description covers the purpose, usage, experimental status, and relationship to the stable sibling. It even notes the response shape matches ask_pipeworx. It doesn't detail return values, but without an output schema and with a simple interface, this is sufficient 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% and every parameter (question plus five aliases) has a clear description. The description adds no new parameter-level semantics beyond saying 'same arguments as ask_pipeworx', but the schema already fully explains the single required question field, so the baseline 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx that acts as a universal router with the same 5,358 tools, arguments, and response shape. It distinguishes itself from the stable sibling by emphasizing the experimental routing improvements, though it could be more explicit about what 'routing' means in this context.

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

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

It explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and references the stable router for comparison. This gives clear context for when to prefer this beta variant, although it doesn't list explicit exclusion scenarios (e.g., when to avoid 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 goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing the extra LLM call cost, the structured return shape, and the detailed refusal reasons (not_in_source, no_tool_match, etc.). This gives the agent a precise model of failure modes and resource implications, which is exactly the kind of behavioral context needed.

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 dense sentences deliver maximum value: the first explains mechanics and return format, the second covers usage context, cost, and alternative. No filler or repetition of schema data. Perfectly front-loaded with the most critical information.

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

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

For a read-only, high-stakes grounding tool, the description covers purpose, routing, extraction behavior, return schema (even though no output schema is provided), refusal reasons, cost, and usage policy. It is complete enough for an agent to invoke correctly without additional 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?

The input schema already covers all 6 parameters with 100% description coverage, and all parameters are aliases for 'question'. The description adds no additional parameter-level meaning, but the schema is self-explanatory, so the baseline of 3 is appropriate.

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

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

The description opens with a specific, verb-driven purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from the sibling tool ask_pipeworx by explaining the core difference: same routing but extracts answers using ONLY the tool result, with evidence and explicit refusals. This makes its unique role unambiguous.

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

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

Explicitly states when to use it ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'). It also names the alternative directly, giving clear decision criteria for an agent.

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

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

Beyond the readOnly/idempotent annotations, the description discloses detailed behavioral traits: resolver confidence model, status short-circuits on low confidence, closed-market handling, wide-spread market flags, cancellation-rule risk, and news fallback mechanisms. This far exceeds the annotations' safety profile.

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 organized with uppercase section headers and front-loaded with the core action and usage. Every section provides decision-relevant details (status codes, constraints), though it could be trimmed for agent parses.

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 thoroughly documents response shapes (market, analysis, evidence), resolver contract fields, parent event extraction, news error fields, safety statuses, and cancellation rules. It covers all scenarios an agent might encounter, making it highly complete.

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

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

The input schema already describes all three parameters (market, depth, include_raw) with 100% coverage. The description reinforces how market values are accepted (slug/URL/question) but adds no new parameter-level details; the fan-out examples are behavioral rather than syntactic.

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 ('Research a Polymarket bet') and names the resource (Pipeworx data). It also states the intended use cases ('should I bet on X', etc.) and gives distinct fan-out examples, clearly distinguishing it from siblings like polymarket_edges or validate_claim.

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

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

It explicitly says 'Use for' with three question types, providing clear when-to-use guidance. It does not name alternatives or state when not to use, but the context is sufficiently clear for 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 the tool read-only, idempotent, and non-destructive, so the safety profile is clear. The description goes further by disclosing concrete behavioral traits: parallel execution, latest 10-K data pull, correct handling of off-calendar fiscal years, sorting by primary metric, and returned paired data with citation URIs. These add substantial value beyond annotations.

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

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

The description is dense and well-structured, front-loading trigger phrases and the core purpose. It is slightly verbose with the repeated trigger examples, but every sentence contributes to the agent's understanding, and the length is justified by the tool's dual-type scope and rich behavioral 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?

For a two-parameter tool with no output schema, the description is remarkably complete. It specifies data sources, return format (paired data + citation URIs), sorting behavior, scope (2–5 entities), and business context (replaces sequential lookups). The agent has everything needed to invoke the tool correctly.

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

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

Schema coverage is 100%, but the description enriches parameter meaning significantly. It maps type='company' to specific metrics (revenue, net income, cash, long-term debt) and type='drug' to FAERS counts, FDA approvals, and trial counts. It also clarifies value formats with examples and notes fiscal year nuances, providing crucial context beyond the schema's generic field 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 explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and provides numerous trigger phrases ('X vs Y', 'rank these companies'). It distinguishes itself from siblings by declaring 'ALWAYS PREFER over sequential single-pack lookups' and 'Replaces 8–15 sequential lookups', making its unique role unmistakable.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides natural-language triggers that signal the appropriate context and explains type-specific usage (company vs. drug), clarifying which data each type retrieves. This makes the tool's selection criteria very clear.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It reveals paid tier for 'thorough', 15-90s latency, outputs gaps[] (never invented), contradictions[], hop field, citation URI, semantic excerpting, and second-hop iteration behavior. No contradiction with annotations; openWorldHint is not contradicted because the tool still accesses a wide structured world.

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 front-loaded with the critical account requirement and then a dense, logically ordered explanation. Every sentence contributes a distinct fact (sources, mechanism, output, timing, alternatives). The length is justified by the tool's complexity, though it could be slightly tightened by trimming redundant examples.

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

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

For a complex research tool with no output schema, the description thoroughly covers return format (findings with evidence+confidence+source+fetched_at), missing-data behavior (gaps[]), contradictions[], hop field, and citation. It also addresses limitations (not open-web, weak on news) and timing. The presence of sibling tools is handled by explicit differentiation. Nothing significant is left ambiguous.

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

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

Schema coverage is 100% with both parameters documented, so baseline is 3. The description adds meaningful nuance: depth enum is expanded with facet counts (3/5/8), the paid implication, and what each hop adds (gap recovery vs. lead-chasing). The question parameter is described as suitable for broad/multi-part questions, aligning with the tool's purpose. This is a clear enhancement over the schema alone.

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

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

The description states a specific verb+resource combination: 'Grounded multi-source research across Pipeworx's 1395 STRUCTURED data sources' and explains the decomposition/parallel routing mechanism. It distinguishes itself from siblings like ask_pipeworx by explicitly contrasting 'one call' vs 'one LLM call' and the structured-data scope. This is unusually precise.

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

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

Explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and even an account-tier fallback ('If you are not signed in, use ask_pipeworx instead'). This is textbook usage guidance with clear alternatives and exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by disclosing the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' It does not detail edge cases like no results, but the core behavior is well disclosed.

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

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

The description is four sentences, each earning its place: the first states the core purpose, the second enumerates supported domains, the third explains the return value, and the fourth gives strategic usage advice. It is front-loaded and contains no fluff, making it both concise and information-dense.

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 adequately explains what the tool returns (top-N tools with schemas and examples) and when to use it. It also clarifies that it is a discovery tool intended for exploring available options, which is complete context for an agent to decide when to invoke 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 description coverage is 100%, with all parameters (query, limit, and aliases) already described in the input schema. The description does not add additional parameter-level meaning beyond what the schema provides; it simply repeats the alias handling already present. Thus, it meets the baseline for high schema coverage without adding extra value.

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 'Find tools by describing the data or task,' which clearly identifies the verb (find) and resource (tools). It goes beyond the title by explaining the search mechanism and explicitly lists many domains (SEC filings, FDA drugs, etc.), distinguishing it from the sibling tools which are specific to individual data sources.

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 exactly when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and contrasts with using a specific tool for a single answer, effectively guiding the agent.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, but the description adds substantial behavioral detail: it fans out across multiple sources, returns specific fields, uses a GDELT→GNews fallback, soft-fails on USPTO patent data due to API sunset, and executes in parallel. It also discloses the exact return structure, which is especially valuable given no output schema.

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

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

The description is dense and front-loaded with realistic user queries, then moves to purpose, fan-out details, output fields, and input constraints. It is longer than minimal but every sentence conveys useful information; the single-paragraph structure is acceptable.

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 thoroughly explains return values (cik, company_name, recent_filings, fundamentals, patents, news, LEI), data source behavior, failure modes, and input requirements. This is enough for an agent to invoke the tool correctly and interpret results.

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

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

Schema covers 100% of parameters with descriptions for both 'type' and 'value', including the ticker/CIK format and name limitation. The description repeats this information without adding materially new semantics, so it meets the high-coverage baseline but does not exceed it.

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

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

The description clearly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call' with concrete examples of user intents. It distinguishes itself from related workflows by explicitly saying it should be preferred over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested.

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 (holistic view requests), states what inputs are acceptable (ticker or CIK), and gives an alternative: 'names not supported (use resolve_entity first if you only have a name)'. This clearly tells the agent when this tool applies and when to use a sibling tool instead.

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, so the destructive nature is known. The description adds usage context but does not disclose additional behavioral traits beyond what annotations provide, such as irreversibility or error handling. It is consistent with annotations, so 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 two sentences, front-loaded with the core action, and each sentence adds value: the first states purpose, the second gives usage guidance and related tools. No wasted words.

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

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

For a simple 1-parameter tool with 100% schema coverage, clear annotations, and no output schema, the description fully covers what the tool does, when to use it, and its relationship to related tools. Nothing critical 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% with the property description 'Memory key to delete'. The description repeats 'by key' but adds no new semantic detail beyond the schema. Baseline of 3 is appropriate since the schema fully explains the parameter.

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

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

The description explicitly states the tool deletes a previously stored memory by key, using a specific verb and resource. This clearly distinguishes it from siblings like 'remember' and 'recall' which are for storing and retrieving memories.

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 scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with 'remember' and 'recall', giving practical workflow guidance without ambiguity.

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

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

Annotations already declare read-only, idempotent, and non-destructive, lowering the bar. The description adds process detail (fetches page, extracts title/description/key links, emits markdown) and output description (single text blob), which goes beyond the structured annotations. No contradictions.

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

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

The description is well-structured and front-loaded with the main action. Two sentences plus a useful-for list convey purpose, process, output, and use cases without waste. 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 tool with 2 params and no output schema, the description is highly complete. It covers what, how, output format, and when to use, complementing the annotations and schema. No significant gaps.

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

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

Schema coverage is 100% (both url and max_links have descriptions), so baseline is 3. The description does not add further parameter context beyond the schema; it mentions extraction of key links but doesn't tie it to max_links. No parameters are undocumented, so a 3 is appropriate.

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

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

The description states the specific verb+resource: "Generate a production-ready llms.txt file for any URL." It clearly distinguishes from siblings by focusing on outputting the standard llms.txt format, rather than visibility checks or competitor scanning.

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 a 'Useful for' list with three concrete use cases (client indexing, own project, competitor audit), giving clear context for when to use. However, it does not explicitly mention when not to use or compare with alternatives, so it falls short of the highest bar.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description adds useful behavioral details: unresolvable fields are returned as null, and the API is keyless and plain-text. This provides context about response shape and access requirements that annotations do not cover.

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

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

The description is two sentences, front-loaded with the core action, and every clause adds value (inputs, outputs, null behavior, API characteristics). No fluff or repetition.

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 single-parameter lookup tool with rich annotations and no output schema, the description fully explains what the tool returns, input types, and potential null fields. It provides all necessary information for an agent to select and invoke the tool correctly.

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

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

The schema description already fully covers the `identifier` parameter, listing all accepted identifier types with an example. The main description repeats this information without adding further parameter-specific semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool performs a one-shot chemical identifier lookup via NCI CACTUS, lists accepted input types (name, CAS, SMILES, InChI, InChIKey) and specific output fields. This distinguishes it from sibling tools like resolve_entity, which likely handle general entities.

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

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

The description makes the intended context clear: use when you have a chemical identifier and need standardized chemical data in one call. It does not explicitly mention alternatives or exclusions, but the specialization inherently differentiates it from sibling tools.

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

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

Annotations already convey safe read-only, idempotent, non-destructive behavior. The description adds value by disclosing the exact return fields and the default behavior of listing only active subscriptions (with an option to include inactive via the parameter). This goes beyond the structured data without contradicting it.

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

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

The description is two sentences, front-loaded with the core purpose, followed by return fields and a use case. Every sentence earns its place with no redundancy or fluff.

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

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

For a simple list tool with comprehensive annotations, no output schema, and a single optional parameter, the description covers all essentials: what it returns, when to use it, and the parameter behavior. There are no significant gaps in 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?

The schema description covers the only parameter (include_inactive) 100%, so the baseline is 3. The description does not add extra meaning about the parameter, but it does indirectly imply the default by contrasting 'active subscriptions' with 'include cancelled subscriptions.' This is adequate but not exceptional.

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: 'List the caller's active subscriptions.' It also lists the return fields (id, type, params, etc.), making the purpose unmistakable. This clearly distinguishes it 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?

The description provides clear context for when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies the alternatives (subscribe/add, unsubscribe/cancel) without explicitly naming them, but no exclusions 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 valuable behavioral context beyond the annotations, including a rate limit ('5 per identifier per day'), that it's free and doesn't count against tool-call quota, and that feedback influences the roadmap. This helps the agent judge when and how frequently to use it.

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

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

The description is moderately long but every sentence adds value: purpose, use cases, content guidance, and constraints. It is well-structured and front-loaded with the primary function.

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

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

The description covers the tool's purpose, usage, content expectations, and limitations. However, it doesn't mention what happens after submission (e.g., confirmation or async processing), and there is no output schema to rely on. Minor gap, but overall complete for a simple feedback tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances parameter understanding by advising to describe issues in terms of Pipeworx tools/packs and not to paste end-user prompts, which clarifies the 'message' field. It also implies the 'context' object should contain tool/pack references.

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: to tell the Pipeworx team about broken, missing, or desired features. It distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback rather than information retrieval.

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

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

It explicitly lists when to use the tool (bug, feature/data_gap, praise) and what to avoid (pasting end-user prompts). This provides strong contextual guidance, though it doesn't name alternative tools, the conditions are precise enough to prevent misuse.

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, and non-destructive behavior. The description goes beyond annotations by adding concrete context: data source (CF analytics-engine), privacy (no PII), output shape ((pack, tool, count)), and caching behavior (5min-1h). This meaningfully enriches the agent's understanding.

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 sized but well-structured: a lead sentence defining the tool, a bulleted list of use cases, and a final technical note. Each sentence contributes value, though the use-case list could be slightly more compact.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains what is returned, the available windows, use cases, data source, privacy characteristics, and cache freshness. No critical information is missing for an agent to decide whether to invoke 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 description coverage is 100% and the parameter description already explains the window enum and its semantics (shorter for hot right now, longer for steady-state). The description adds a default ('24h') and reiterates the window options, but does not provide additional parameter-level meaning beyond the schema.

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

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

The description uses a specific verb ('Returns') and clearly defines the resource: top tools, top packs, and total call volume over a time window. It distinguishes from siblings by emphasizing its social-proof/trending nature ('What other AI agents are calling...'), which is unique among the sibling tools like discover_tools or recent_alerts.

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

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

Provides explicit 'Useful for' scenarios (discovering hot data sources, confirming canonical tool choice, aligning with agent needs). This gives clear context for when to use it, though it does not explicitly state when not to use it or name alternative tools.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses internal heuristic details: Jaccard similarity threshold of ≥0.30, placeholder fraction filter (>20% returns null), the 3pp deviation threshold for partition signals, and the fill-check distinction between theoretical and realizable edge. It also warns 'do not trade it' when realizable edge ≤0, which is critical behavioral context. 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 lengthy but densely packed with valuable information, using clear structural labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK, Response) to organize sections. It opens with a one-sentence purpose, then methodically covers modes, heuristics, filters, and output format. Every sentence serves a purpose, and the structure aids scanning without redundancy.

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

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

Given the tool's complexity (three modes, multiple heuristics, response structure, fill-check caveat) and the absence of an output schema, the description is remarkably complete. It explains inputs, processing, filters, response fields, and trading advice, and even references a sibling tool for deeper risk modeling. No significant gaps remain for an agent to invoke the tool correctly.

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

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

While the input schema already covers both parameters with 100% description coverage, the tool description adds substantial extra meaning. It explains what an 'event' slug looks like, that full URLs are accepted, how 'topic' searches related events, and what the no-args default does. It also details the internal processing for each parameter (e.g., walking child markets, partition checks, cross-event flattening), enriching the schema far beyond simple type/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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings by naming the exact mechanism and pointing to polymarket_fill_risk for a complementary capability. This leaves no ambiguity about what the tool does and how it differs from related tools.

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

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

The description explicitly states when to use each invocation mode: 'Call with NO args for a trending_scan...', 'pass event...', or 'topic...'. It gives a recommendation ('event (recommended for a specific market)') and contrasts cross-event vs single-event use cases. It also addresses when not to trade and directs users to polymarket_fill_risk for custom sizing, effectively covering both when-to-use and alternatives.

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

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

The description goes far beyond the read-only and idempotent annotations, disclosing rich behavioral details: 1-hour caching keyed on all knobs, a 24h-move warning when edge may already be priced in, exclusion of Fed bets from ranking with a clear reason, diagnostics explaining why segments may be empty, and the nuanced per-leg Kelly behavior for partition arbs. This is comprehensive operational 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 long but exceptionally dense and well-organized. It front-loads the core purpose, then systematically details model families, response segments, knobs, and diagnostics. Every sentence adds operational value, and the structure (using parentheses and clear sectioning) makes the length manageable and purposeful.

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

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

With no output schema, the description fully compensates by detailing the response structure (by_segment, fed_candidates, _diagnostics), the fields on each opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.), and edge-case behaviors like placeholder filters and partition Kelly caveats. It leaves the agent with a clear mental model of what to expect and why.

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?

While the schema already covers 100% of the parameters' basic descriptions, the tool description adds crucial semantics that influence how parameters should be used. For example, it explains why min_kelly does not filter partition arbs (they have kelly_fraction_half=0 by design), and it gives a real-world rationale for slippage_pp default (zero fees but 20-50bp bid/ask costs). This significantly enhances parameter 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 leads with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly frames the tool's purpose for opportunity discovery ('Built for what should I bet on today') and distinguishes it from related tools like arbitrage or edge tracking, which likely serve different specific functions.

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 strong usage context: it is for discovering betting opportunities without paging through hundreds of markets, and it details tradeable-edge knobs that tell the caller how to filter results. However, it does not explicitly name sibling alternatives or when not to use this tool, so it misses the full 'when vs alternatives' guidance that would earn a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description adds substantial behavioral detail: history depth bounded by 60-day snapshot TTL, snapshots written on cache-miss, gaps mean no scan, and decay computed from daily closes not intraday. This goes well beyond annotations and clarifies data availability and computation caveats.

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?

Although the description is longer than a typical one-liner, every sentence serves a purpose: purpose, parameters, response format, and limitations are clearly separated and front-loaded. The structure is logical and dense without fluff or repetition, 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?

With no output schema, the description fully explains the return structure (tracked[], expired[], snapshot_dates[]) and covers edge cases like gaps, TTL limits, and signed edge values. It is comprehensive for the tool's complexity and leaves no critical gaps in agent understanding.

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

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

The input schema already has 100% coverage with descriptions for both 'days' and 'window', but the description adds value by explaining 'window' as a snapshot family and clarifying that decay numbers are based on daily closes. It reinforces the schema and adds interpretive context, exceeding the baseline for full schema coverage.

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

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

The description states a specific verb ('edge persistence and decay telemetry') and resource ('daily polymarket_edges snapshots'), answering a clear question: 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence and decay rather than current edge listings.

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

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

The description clearly implies when to use this tool: when you need to assess whether an edge is long-standing or decaying, and contrasts fresh vs. old wide edges to illustrate the trade-off. It does not explicitly name alternative tools or provide 'when not to use' exclusions, but the context is strong enough to guide 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 mark the tool readOnly, openWorld, idempotent, and non-destructive; the description adds substantial behavioral detail: it 'walks the ladder', returns specific fields like top_of_book and forced_directional_risk, and warns about partial basket fills creating unhedged positions. No contradiction with annotations.

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

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

The description is long but densely packed and well-structured, using clear sections (SINGLE-MARKET, BASKET) and front-loaded purpose. Every sentence adds operational detail, and the length is justified by 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?

The description covers all key aspects: inputs, modes, return values, failure modes, risk warnings, and usage context. Even without an output schema, it enumerates the important result fields (tops_of_book, vwap_fill_price, slippage_pp, etc.) and explains the dominant loss mode, making it complete for realistic decision-making.

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 deep parameter semantics: it distinguishes single-market vs basket interpretation of `market`/`event`, explains `side` defaults and overround/underround logic, and defines `size_usd` as settlement notional for baskets. This goes well beyond the schema's basic property 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 opens with a crisp, specific definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the tool from siblings by naming polymarket_arbitrage and polymarket_edges and explaining its role as a pre-trade validation 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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (thin books, partial-fill risk), giving clear context and exclusions.

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

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

The description goes far beyond the annotations by disclosing key behavioral traits: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and skipped_cross_type/subtype counters. It explains what these mean and why the spread may be invalid. This is rich, honest context that annotations alone do not 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 well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Every sentence provides useful detail, especially the safety-field explanations and the caution about pre-mapped topics. While not terse, the length is justified by the tool's complexity.

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

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

Given there is no output schema, the description fully explains the response structure (leg-by-leg prices, matched spread, top_spreads_pp) and the safety fields. It also covers when spreads are meaningful, temporal alignment implications, and the meaning of skipped counters. For a tool with multiple modes and complex caveats, this is a complete and self-contained explanation.

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 covers 100% of parameter descriptions, including the valid topic values and the override behavior of kalshi_event_ticker and polymarket_event_slug. The description adds some context about the two modes and how parameters interact, but it does not substantially go beyond what the schema already documents. Baseline 3 applies because the schema carries the 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 clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings by specifying the two venues and the concept of a spread, and by naming two distinct modes (topic shortcuts vs. explicit ticker/slug). The verb 'spread' and the resource naming are specific and unambiguous.

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

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

The description provides explicit guidance on when to use each mode: 'topic' for macro shortcuts and explicit ticker/slug for custom pairings. It also warns that most pre-mapped topics return compatibility warnings and that pre-mapped does not mean tradeable. However, it does not explicitly contrast with alternative tools (e.g., polymarket_arbitrage) or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds scoping context ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the ability to list all keys by omitting the argument, which are behavioral nuances beyond the annotations.

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

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

The description is only three sentences, front-loaded with the core action and structured logically: function, use case, scope, and related tools. Every sentence adds value with no redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers purpose, usage, scoping, and relationships to other tools. It doesn't specify the return format or error behavior, but the action 'Retrieve' implies the return value, making the description reasonably complete for an agent.

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

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

Schema coverage is 100%, so the parameter 'key' is fully described in the schema. The description reinforces this with 'omit the key argument' and provides concrete examples of what keys represent (target ticker, address, research notes), adding useful context beyond the schema.

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

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

The description begins with specific verbs 'Retrieve' and 'list', names the resource ('value previously saved via remember' / 'all saved keys'), and distinguishes from sibling tools by explicitly referencing 'remember' and 'forget' in the pairing sentence. This clearly differentiates 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?

Provides explicit use cases ('look up context the agent stored earlier — the user's target ticker, an address, prior research notes') and mentions the conditional 'omit the key argument' for listing. It doesn't explicitly state when not to use it, but there are no direct alternatives for retrieval, so the guidance is strong. A 5 would require explicit exclusions.

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

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

The description directly contradicts the annotations. Annotations declare readOnlyHint=true and idempotentHint=true, but the description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' implying a state-changing side effect. This is a clear contradiction, grounding the score at 1 per the rubric.

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, ~90 words, and front-loaded with purpose, then return format, filtering, mark_read semantics, and an alternative endpoint. Every sentence earns its place with no redundancy or fluff.

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

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

Given 5 optional parameters and no output schema, the description covers essential return payload details (source, citation_uri, raw payload), filter mechanics, mark_read side effects, and even an HTTP alternative. It omits minor edge cases like pagination behavior or rate limits, but these are adequately covered by the schema and annotations.

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

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

Schema coverage is 100% with good descriptions for all 5 parameters. The description goes beyond the schema by giving a concrete type example ('sec_8k') and explaining the behavioral consequence of mark_read on subsequent calls. This adds genuine semantic value, pushing 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 opens with a specific verb+resource: 'Pull fired events from your subscription feed.' It clearly distinguishes this tool from siblings like list_subscriptions by focusing on retrieving fired alerts rather than managing subscriptions. It also specifies what the returned alerts contain, solidifying purpose.

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

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

The description gives clear context for use: filtering by type/since and marking read, plus notes that polling works fine. It names an alternative (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, which implicitly contrasts with this tool's interactive use. It lacks explicit exclusions, but the context is strong enough for a 4.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the tool's fan-out to multiple APIs, the fallback chain, and the USPTO soft-fail due to PatentsView sunset. This significantly enriches the behavioral model for an agent, especially since no output schema 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?

Despite being dense, the description is efficiently structured: it opens with example queries, then lists sources and fallbacks, parameter formats, return structure, and ends with the alternative tool. Every sentence carries operational value; no fluff or repetition.

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 (multi-source, fallbacks, parameter variants) and the absence of an output schema, the description fully covers return values (changes[] grouped by source, total_changes, citation URIs) and source behavior. It leaves no critical ambiguity for an agent to resolve.

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 a practical recommendation ('Use 30d or 1m for typical monitoring') and clarifies the 'value' parameter's two acceptable forms (ticker or CIK), providing a small but meaningful edge over the raw 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 this is a change feed for a company over a recent window, with concrete example queries ('What's new with X'). It names the specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes it from the sibling tool entity_profile, making its purpose unmistakable.

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

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

Provides explicit usage context with query paraphrases and fallback behavior (GDELT→GNews). Directs users to entity_profile when they need a static profile, which is a clear alternative. This gives strong when-to-use vs. when-not-to-use guidance.

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

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

Annotations already cover idempotency and non-destructiveness. The description adds valuable context about scoping by identifier and persistence behavior (24 hours for anonymous sessions, persistent for authenticated users). It does not contradict annotations.

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

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

Four sentences, front-loaded with the primary purpose. The examples and usage guidance earn their place, though slightly verbose in listing cases; still 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?

For a simple key-value write tool with complete schema coverage and no output schema, the description covers use cases, persistence, scoping, and sibling relationships. No critical gaps remain.

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

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

Schema description coverage is 100% for both parameters, with examples in the schema. The description only reinforces the key-value concept without adding new parameter-specific details, so the baseline 3 applies.

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

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

The description uses a specific verb ('Save') and a clear resource ('data... key-value pair'), and explicitly states the scope ('across this conversation or across sessions'). It also distinguishes from siblings by mentioning 'Pair with recall to retrieve later, forget to delete.'

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 an explicit 'Use when' list with concrete examples (resolved ticker, target address, user preference, research subject), and directly names alternative tools for related operations (recall, forget).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond these: 'Keyless, plain-text API' reveals authentication requirements and response format, and 'single representation' clarifies the output behavior. This enhances transparency without contradicting annotations.

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

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

The description is compact and front-loaded. The first sentence names the resolver, the second specifies exact inputs, outputs, and their meanings, and the third adds the auth/format note. Every sentence earns its place with 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 conversion tool with only two parameters and no output schema, the description covers input types, output representation options, response format, and authentication. It does not mention error handling or rate limits, but these are not critical for a keyless, idempotent API. It also does not explicitly contrast with sibling tools, which slightly limits completeness.

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

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

The input schema already has 100% coverage with descriptions for both parameters. The tool description goes further by explaining what each representation value means (e.g., 'smiles (canonical SMILES)', 'stdinchi (standard InChI)'), which adds meaning beyond the bare enum list in the schema.

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

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

The description explicitly states the action ('Convert'), the resource ('chemical identifier'), and the output ('single representation') with a detailed list of possible output types. It clearly distinguishes itself from sibling tools like 'resolve_entity' by its specific focus on chemical identifiers and the NCI CACTUS resolver.

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

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

Usage is implied through the purpose: use when you need to convert a chemical identifier to a standard representation. However, it does not explicitly mention alternatives, when not to use, or provide any exclusion criteria relative to the many sibling tools.

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

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

Annotations already mark the tool as read-only, idempotent, and safe (readOnlyHint, idempotentHint, destructiveHint=false). The description adds rich behavioral detail: internal cascading through multiple lookup endpoints, auto-disambiguation, and the format of returned citations (pipeworx URIs). This goes well beyond the annotations and fully discloses the tool's 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 longer than necessary but well-structured and front-loaded with usage context. It avoids fluff and each sentence contributes either usage guidance, type-specific return details, or behavioral notes. Some redundancy exists with schema descriptions, but overall it is efficient.

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

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

With no output schema, the description fully compensates by detailing return content per type (ticker, CIK, company name, citation URI for companies; RxCUI, ingredient, brand, citation URI for drugs). It also covers input formats, disambiguation, and the internal lookups, making the tool's behavior predictable and 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%, so the baseline is 3. The description enhances parameter understanding by providing concrete examples for each type and value (e.g., 'AAPL', '0000320193', 'ozempic') and clarifying that the value field accepts multiple formats with auto-disambiguation. This adds value beyond the schema's property 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 verb and resource: it resolves a user-spoken name to the canonical/official identifier required by other tools. It lists supported entity types (company, drug) and specific outputs, making it unambiguous and distinct from sibling tools that use identifiers rather than resolving them.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also frames the tool as a replacement for 2-3 manual lookups. However, it does not explicitly mention alternative tools (e.g., 'identify' or 'resolve') or when not to use this tool, missing the highest bar.

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 establish read-only, idempotent, non-destructive behavior. Description adds meaningful behavioral context: it internally probes each entity with ai_visibility_check, ranks results, and returns per-entity score, confidence, and signal density. No contradiction.

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

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

Three sentences, front-loaded with main action, includes a concrete use-case quote and return format. No filler or redundancy.

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

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

For a tool with no output schema, description supplies return shape (ranked list with score, confidence, signal density), input semantics (your brand + competitors), and relationship to ai_visibility_check. Combined with full schema coverage and clear annotations, it's complete enough for reliable selection/invocation.

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

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

Schema already documents all 4 parameters with 100% coverage, including entity order and special _apiKey semantics. Description doesn't add parameter-level detail beyond schema, so baseline 3 applies.

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

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

Description opens with 'Compare AI visibility across multiple entities side-by-side', a specific verb+resource pair that clearly distinguishes from single-entity sibling ai_visibility_check. It further states it probes with ai_visibility_check, ranks by score, and returns a ranked list, making the purpose unambiguous.

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

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

Clearly frames when to use: competitive AI-marketing audits and gives an illustrative question ('does Claude know about us as well as our competitors?'). It doesn't explicitly name alternative tools or exclusion criteria, so not a 5.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable context: partial failure degrades gracefully, bundlephobia's first measurement can take 5-30s and may time out, with sources_failed listing it. It also discloses NPM-only limitation, going beyond annotations.

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

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

The description is comprehensive but efficiently packed; each sentence contributes either use cases, output details, or failure behavior. It is longer than minimal but justified for a composite tool with multiple data sources.

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 enumerates the returned fields precisely, lists alternative versions and links, and explains timeout behavior. Together with the annotations, it gives a complete mental model of the tool's capabilities and limitations.

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

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

The schema description covers both parameters fully (100%). The description restates that package is an npm package name and version defaults to latest, but adds no new parameter-level information beyond what the schema provides. This matches the baseline for full schema coverage.

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

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

The description clearly identifies the tool as a composite npm package evaluation check, combining deps.dev and bundlephobia data. It uses specific verbs ('scan', 'check') and distinguishes itself from siblings by naming the data sources and output fields.

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 an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion: NPM-only in v1, pointing to deps.dev:version for other ecosystems, thus guiding to the correct sibling.

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 idempotent behavior, and the description adds crucial details: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation, and character offsets for verification. This goes far beyond the structured annotations, fully disclosing the tool's inner workings.

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 yet compact, with every sentence serving a purpose: purpose, usage, pairing, and technical details. It is front-loaded and efficiently structured, avoiding any 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?

Even without an output schema, it explains the return format (passages with offsets and similarity scores), the truncation behavior, and the algorithmic basis (BGE-base-en, cosine over windows). This gives a complete picture for an agent to select and invoke the tool confidently.

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

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

Schema coverage is 100% with each parameter described, giving a baseline of 3. The description adds meaningful examples for `text` (SEC 10-K, article) and `query` (supply-chain risk, fiscal year 2024 revenue), and clarifies `limit` by mentioning 'top-N passages'. This enriches parameter 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 opens with 'Semantic search INSIDE a fetched record' and clearly specifies inputs and outputs, distinguishing it from sibling tools that likely perform broader retrieval. It names specific examples like SEC 10-K bodies and articles, making the purpose unmistakable.

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

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

It explicitly states when to use the tool ('when the record is too big to cram into the prompt') and pairs it with ask_pipeworx_grounded, giving a clear workflow. This provides strong contextual guidance without needing explicit 'when not to use' clauses.

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

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

Beyond annotations (readOnly=false, idempotent=true), the description discloses authentication prerequisites (OAuth account required), subscription id returns, phone verification requirement, a 10/day SMS cap, and webhook auto-disabling after 10 consecutive failures. This gives substantial behavioral context that annotations do not 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?

Despite its length, every sentence carries high-value information: purpose, return, auth requirement, types, channels, and caveats. It is front-loaded with the core verb and resource, then logically organizes details. No filler or redundancy with the schema.

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

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

The tool has three parameters, two required, with nested objects and no output schema. The description covers auth constraints, type-specific params, delivery options, and return value, making it fully self-contained for an agent to understand usage. The lack of an output schema is compensated by the statement 'Returns the new subscription id.'

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

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

The input schema already has 100% parameter description coverage, so the baseline is 3. The description adds concrete examples for each subscription type (e.g., sec_8k items:["5.02"], polymarket_edge topic:"fed") and clarifies delivery constraints like verified phone numbers, enriching the meaning 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 opens with a clear, specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also states the return value (new subscription id) and lists supported types, making it easy to distinguish from sibling tools like list_subscriptions or 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?

The description provides explicit context on when to use the tool through its supported types (sec_8k, polymarket_edge, fred_series) and delivery channels. It also states a clear when-not: anonymous and BYO accounts cannot persist subscriptions. However, it does not explicitly name alternative tools for listing or removing subscriptions, so it misses full marks.

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 this as readOnly and non-destructive, so the safety profile is covered. The description adds meaningful behavioral context by explaining that it returns category-bucketed example questions with exact tool and argument shapes, drawn from a live catalog of thousands of tools, and that it can be called with no arguments or a topic filter. This goes beyond a simple 'returns suggestions' and gives the agent a clearer picture of what to expect.

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 search-like queries to orient the agent, then clearly states the tool's purpose, return content, and usage. It is a bit long (about 90 words) but every sentence contributes value, including the list of categories and the advice to use it first. It could be tightened by removing some thesaurus-like phrases, but it remains well-structured.

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

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

Given that there is no output schema, the description fully explains what the tool returns: category-bucketed example questions with the exact tool and argument shape that answers each. It also covers how to call it (no args for full spread, topic to focus) and when to use it (onboarding). The mention of meta-tools adds extra context for integration. No critical gaps are apparent.

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

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

The schema already covers the lone `topic` parameter with a full description of options and behavior (omit for full spread), giving 100% schema coverage. The description adds example values like 'finance', 'pharma', and 'betting' but does not materially improve on the schema's semantic clarity. Since the schema does the heavy lifting, the baseline of 3 is appropriate.

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

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

The description clearly states that this tool is the onboarding entry point for discovering what to ask Pipeworx, returning category-bucketed example questions with exact tool and argument shapes. It uses specific verbs ('Returns', 'Call') and distinguishes itself from siblings by positioning it as the 'FIRST' tool to use when unfamiliar with Pipeworx, which is a unique role among the listed sibling tools.

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

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

The description explicitly says to use this tool FIRST when you do not yet know what Pipeworx can do, and provides guidance on how to call it with or without a topic parameter. It also mentions learning how to call meta-tools, which serves as an alternative use case. This is clear when-to-use guidance, although it does not explicitly state when not to use it.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that ownership is enforced and that the row is deactivated rather than deleted, preserving historical events via recent_alerts. This adds meaningful behavioral context.

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

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

The description is two sentences, front-loaded with the primary action, and contains no filler. Each sentence adds value: the first states the action, the second explains ownership and deactivation behavior.

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 one-parameter tool with strong annotations, the description covers the essential context: how to cancel, ownership restrictions, and the soft-delete behavior. It also connects to recent_alerts for historical data, making it adequately 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?

The input schema already provides a complete description of the id parameter (uuid returned by subscribe). The description adds no additional parameter-specific detail, so it relies on the schema's 100% coverage.

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

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

The description opens with a specific verb and resource: 'Cancel a subscription by id.' This clearly states the action and target, and distinguishes it from sibling tools like subscribe and list_subscriptions.

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

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

The description provides clear context for when to use the tool (to cancel a subscription) and includes the ownership constraint. However, it doesn't explicitly state alternatives or exclusions, such as if there is a different tool for permanent deletion.

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, covering safety. The description adds valuable behavioral context beyond annotations: the two-pipeline routing, the return format (verdict, value, citation, reasoning), and the efficiency claim of replacing 4–6 sequential calls. No contradictions with annotations.

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

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

The description is longer than the calibration high example but remains dense and well-structured. It opens with relatable examples, then states the core function and routing, and closes with output details. Every section earns its place, though the list of intent phrases is somewhat redundant with the schema's claim description.

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 lists what the tool returns (verdict types, actual value with citation, reasoning), explains the two execution paths, and covers the full scope of claims. The annotations and schema address safety and parameters. This is a complete description for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The main description does not repeat parameter details; all semantics (claim example, tolerance_pct range, defaults) are fully captured in the input schema. The description adds no additional meaning beyond what the schema already 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 clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific verb+resource ('validate claim', 'verify the claim') and distinguishes itself from generic research tools by using examples like 'fact check' and 'confirm or refute.' It also differentiates from siblings by describing a two-path routing (SEC EDGAR for company-financial claims, grounded pipeline for other claims).

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 whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use guidance. It also explains the routing logic for different claim types. However, it does not mention alternatives or explicit when-not-to-use cases (e.g., comparative claims might be better served by compare_entities), so it falls short of a full 5.

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