dadjokes

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds valuable behavioral context beyond that: the default free model, that `_apiKey` is passed straight through to Anthropic, and that the user pays Anthropic directly. It does not discuss rate limits or failure modes, but the annotations cover the core 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 three sentences, front-loaded with the primary action, then adds cost/usage details, and concludes with use cases. Every phrase earns its place; no filler or repetition of structured fields.

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

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

With no output schema, the description appropriately summarizes the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'). It also covers the main parameter behaviors, cost implications, and intended use cases, making it complete for a read-only, non-destructive probing tool with moderate 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 schema fully documents each parameter. The description adds meaning by explaining the default model selection, the conditional requirement for `_apiKey` when probing Anthropic, and the significance of the `models` array. This goes beyond a simple restatement of 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 a specific verb ('Probe') and a clear resource ('one or more LLMs') plus the core function: scoring visibility (0-100) per model. It distinguishes itself from siblings like ask_pipeworx or deep_research by focusing on LLM knowledge and visibility scoring for business 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?

It states explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies the default model and optional Anthropic key. However, it does not name alternative tools or provide when-not-to-use guidance, so it falls short of the highest bar for 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?

Annotations already establish that the tool is read-only, open-world, idempotent, and non-destructive. The description adds useful context by explaining that the tool routes to 5,767 tools across verified sources, auto-fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It does not contradict the annotations and gives meaningful behavior beyond the structured hints.

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

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

The description is heavily duplicated: the main paragraph listing domains, trigger phrases, and examples is repeated almost verbatim, roughly doubling the length. This wastes tokens and violates the principle that every sentence should earn its place. The information is well-organized, but the repetition is a significant structural flaw.

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 broad routing tool, the description is quite complete: it lists supported domains, example queries, when to prefer it, and what the output looks like. It also makes clear that the tool handles authoritative structured data with citations. It does not discuss failure behavior or edge cases, but given the annotations and schema, it provides enough context for correct invocation.

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

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

The schema coverage is 100%, and the schema explains that all parameters are aliases for the natural-language question. The description adds value by clarifying that the tool itself 'fills arguments' for the underlying tools, which helps the agent understand that only a high-level question is needed. It does not go into detailed parameter constraints, but the schema already covers the aliases.

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 ask_pipeworx routes factual questions to the right external tool, fills arguments, and returns structured answers with citations. It is specific about the domains covered and the kinds of questions it handles. However, it does not explicitly differentiate itself from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded.

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 strong, explicit usage guidance: prefer over web search, use for trigger phrases like 'what is' and 'look up', and start here for most questions. It provides concrete examples and says the tool should be used even when web search could answer. It does not mention when to switch to specific sibling alternatives, so exclusion guidance is incomplete.

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 (read-only, idempotent, non-destructive), and the description goes well beyond them. It discloses the beta/experimental status, the live candidate-swapping mechanism, the current in active state, and the fact that results are compared against the stable router to decide merges. This gives an agent a clear and honest picture of how behavior may shift over time, which is exactly the kind of context that annotations alone cannot 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 longer than average but each sentence contributes distinct information: beta identity, identical surface, candidate status, usage directive, and non-fallback assurance. It is front-loaded with the key beta context and ends with a clarifying emphasis. It could be slightly tightened, but it remains well-structured and scannable.

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 and six alias parameters, the description supplies the essential call context: use like ask_pipeworx, pass natural language, expect the same response shape, and accept that routing may change when a candidate is active. It relies on knowledge of the ask_pipeworx sibling for exact response shape, but names that sibling so the agent can resolve it. The alias list is already in the schema, so not repeating it is acceptable.

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

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

Schema description coverage is 100%: every parameter is documented as an alias for 'question', and the canonical parameter explains that it accepts query, q, prompt, text, and input. The description only adds a cross-reference that arguments match ask_pipeworx, which is useful but not essential since the schema already carries the parameter documentation. Baseline 3 is appropriate when the schema handles the full semantic load.

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

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

The description clearly identifies this as a beta universal router identical to ask_pipeworx, with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling and from ask_pipeworx_grounded by its experimental candidate-routing purpose. The core user-facing function—asking a natural-language question to get routed to a tool—is implied through 'universal router' and 'use it exactly like ask_pipeworx' but never stated directly.

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 it exactly like ask_pipeworx when you want the newest routing, naming the stable sibling as the alternative and the condition for choosing this beta. It also clarifies that it is a full working router, not a fallback, and that currently no candidate is active so it matches ask_pipeworx exactly. This is strong usage guidance, though it does not enumerate when to choose other siblings like ask_pipeworx_grounded.

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 read-only and idempotent annotations, the description discloses refusal behavior with specific reason codes, return shape including evidence as verbatim quote, and the extra LLM call cost. This gives substantial transparency about edge cases and failure modes.

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 its core purpose and returns, then refusal behavior, then usage guidance and cost. It is detailed but every clause adds context that an agent needs to select and rely on the tool correctly.

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, the description thoroughly explains the success and refusal return shapes, the evidential nature, the routing behavior, and the cost implications. Nothing critical is missing for an agent to understand when and how to invoke this tool.

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

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

Schema description coverage is 100%, so the schema fully documents the question parameter and its aliases. The description adds no additional parameter-level detail, which is fine since the schema already handles 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 identifies a specific verb and purpose: a hallucination-resistant answer mode that extracts only from tool results. It explicitly distinguishes itself from ask_pipeworx by noting the same routing but grounded extraction, which differentiates it from its key sibling.

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

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

Usage guidance is explicit: use when answers will be quoted, cited, or acted on and facts must not be invented, with named examples. It also states when not to use it, recommending ask_pipeworx as noted in the description for casual lookups, plus a cost tradeoff.

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

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

Annotations declare readOnly/openWorld/idempotent, and the description adds a wealth of behavioral detail beyond that: resolver contract with market_match_confidence and suggestions, low-confidence short-circuit with status, closed/dead market handling, news fallback flags, wide-spread illiquidity notes, and resolution-rule risk parsing. This goes far beyond annotations and gives the agent clear 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 lengthy but well-structured with clear labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every section adds useful information for a complex tool, but it could be tightened; some details like the de-indexing explanation are slightly redundant with the low-confidence path. Overall it earns its place.

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

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

With no output schema, the description thoroughly explains the response structure (result.market, result.analysis, result.evidence, parent_event, news fields), statuses, and edge cases. It also warns about resolution-rule risk and resolver confidence, making it highly complete for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the market input forms already in the schema and does not add meaningful extra info about depth or include_raw. It provides contextual color about the fan-out behavior but not parameter-level semantics beyond what the schema states.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further details the input forms (slug, URL, question text) and the output (evidence packet + market-vs-model comparison), clearly distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description explicitly states when to use it: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides context about blocker statuses and resolution-rule risk checks. However, it does not explicitly name alternative tools or when-not-to-use, so it falls short of a 5.

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

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

Annotations already indicate readOnly and idempotent behavior. The description goes further by detailing exact data sources (SEC 10-K financials, FAERS counts, FDA approvals, trial counts), how off-calendar fiscal years are handled, and that results are sorted by primary metric. This adds substantial transparency 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 appropriately sized—about five sentences—but each sentence carries essential information: trigger phrases, the core function, data details, sorting behavior, and efficiency benefits. It is front-loaded with purpose and usage, making it highly scannable.

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 without an output schema, the description is remarkably complete. It explains what data is pulled, how results are organized, and that returned data includes citation URIs. Edge cases like off-calendar fiscal years are noted, ensuring the agent has full context 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?

Although schema coverage is 100%, the description enriches both parameters. It explains the semantic difference between type='company' and type='drug', provides concrete examples like ["AAPL","MSFT"] and ["ozempic","mounjaro"], and clarifies that values map to tickers/CIKs or drug names. This goes beyond the schema's basic type definitions.

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's purpose: side-by-side comparison of 2–5 companies or drugs in a single call. It provides trigger phrases like 'X vs Y' and 'rank these companies,' and distinguishes itself from single-entity lookups by explicitly stating it should be preferred over sequential lookups.

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 usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It lists concrete query patterns and explains when type='company' vs type='drug' should be used. This clearly informs the agent when to select this tool over alternatives.

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

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

Annotations only declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial behavioral context beyond these: account/plan requirements, 15-90s latency, gap[] reporting with no invented findings, contradictions[], hop fields, resolvable citation_uri conditions, and semantic excerpting. This fully discloses the tool's non-obvious 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 dense and front-loaded with the critical account requirement, and every clause contributes operational detail. However, it is one very long paragraph mixing auth, alternatives, internal mechanics, output format, and latency, which makes it slightly harder to scan. No filler, but structure could be improved.

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 carries the burden of defining the return contract, and it does so thoroughly: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and citation_uri. Combined with latency and alternative routing, an agent has everything needed to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already explains both question and depth semantics, including facet counts, hops, and contradictions. The description adds a paid-plan restriction for thorough and latency context, but it does not meaningfully change parameter understanding beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: grounded multi-source research across Pipeworx's 1,506 structured data sources, decomposing questions into facets and routing to 5,767 tools in parallel. It explicitly distinguishes itself from open-web search and from ask_pipeworx, making sibling differentiation clear without needing to inspect the schema.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use ask_pipeworx if not signed in, prefer ask_pipeworx for single lookups and for breaking/current-news topics, and use deep_research for broad/multi-part questions over structured data. It also explains depth-level behavior, so an agent can choose the right variant.

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 that the tool is read-only, idempotent, and non-destructive. The description adds valuable behavior context beyond these: it explains the return format (top-N tools with names, descriptions, full input schemas, and curated examples), states that results are 'ready to call directly' with no second schema lookup, and positions the tool as a first-step meta-query. This meaningfully extends the annotation-only picture, though it does not describe edge cases like empty result sets or error 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 front-loaded with the core purpose in the first sentence, then gives a useful domain list, followed by the return-value detail and a clear usage directive. It is a bit longer than necessary due to the domain enumeration, but every part contributes to selection and invocation confidence. No fluff or redundancy. The structure flows logically from what → when → what you get → when to use it.

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

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

This tool has no output schema, so the description carries the full burden of explaining what the agent will receive. It explicitly states that returns include names, descriptions, and full input schemas with examples, and that results are directly callable. It also explains the query parameter semantics and gives clear usage context (call first). Given the tool's role as a discovery tool, this description covers all essential aspects for correct use. There is no missing information that would cause an agent to misuse 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?

All parameters (including aliases) are fully described in the schema, so the baseline is 3. The description reinforces the meaning of 'query' by calling it a 'natural language description' and providing examples ('analyze housing market trends'), but it does not add new parameter-specific semantics beyond what the schema already states. The description's mention of 'top-N' indirectly relates to the 'limit' parameter, but not in a way that clarifies syntax or defaults over the schema. Thus, no extra credit.

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 combination: 'Find tools by describing the data or task.' It clearly names the tool's function as a discovery/search mechanism and even enumerates the domains it covers (SEC filings, FDA drugs, etc.), making it unmistakable what this tool does. It also distinguishes itself from sibling tools by positioning itself as a meta-tool ('Call this FIRST'), so it is not confused with specific research or lookup 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 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.' This is strong usage guidance. It does not name specific alternatives (like sibling tools), but the priority instruction and the 'not just one answer' clause implicitly communicate when not to use it (when you need a single answer). Missing explicit 'when-not' examples keeps it from 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?

Beyond readOnly/idempotent annotations, the description discloses parallel fan-out, soft-fail behavior (USPTO), that empty sections mean genuine no-data, and what happens for private companies. These are non-obvious behaviors an agent needs before calling.

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 definition is dense and front-loaded with examples, and every section adds necessary operational detail for a complex multi-source tool. The single-paragraph wall of text is long, so it loses a point for scannability, but nothing is 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?

With no output schema, the description carries the full burden of explaining return values, and it does so comprehensively: sources, output fields, URI format, sorted fundamentals, and failure semantics. The agent has everything needed to invoke it correctly.

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

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

Schema coverage is already 100%, but the description adds real value by stating that type and value are interchangeable, that names resolve via SEC EDGAR's company-name match, and that private companies yield resolved:false. This goes beyond simply restating 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 concrete user-phrase examples and states 'full cross-source profile of a US public company in ONE parallel call,' immediately identifying verb, resource, and scope. It also contrasts itself with 'single-pack SEC/XBRL/news lookups,' distinguishing its purpose from likely siblings.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack...lookups when the user asks for a holistic view,' telling the agent exactly when to choose this tool. It also covers edge-case routing for private companies (resolved:false with notes).

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 destructive and non-read-only behavior. The description adds context that the memory was 'previously stored' and 'saved earlier,' reinforcing it only affects agent-saved data. This is useful but not substantial 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 two sentences with the main action front-loaded, followed by usage guidelines and related tools. Every sentence earns its place with no redundant information.

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

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

For a simple single-parameter tool, the description covers purpose, usage, and related tools. Annotations handle destructive and idempotent aspects, and no output schema is expected. It could explicitly mention irreversibility, but destructiveHint already signals this.

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 has 100% coverage for the 'key' parameter with 'Memory key to delete.' The description's 'by key' merely repeats the schema, adding no new meaning. Baseline 3 is appropriate since schema fully documents 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?

Description clearly states 'Delete a previously stored memory by key,' identifying the specific action and resource. It distinguishes itself from siblings by mentioning pairing with remember and recall, making its role in the memory workflow explicit.

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 scenarios: when context is stale, task is done, or clearing sensitive data. It names related tools (remember and recall) but does not explicitly state when to use those alternatives instead of forget, so it lacks full when-not guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond annotations: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It also describes the output as a single text blob for drop-in placement, which is useful for the agent. The description does not contradict annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, then process, then use cases. Every sentence earns its place without wasted words. It is concise and well-structured for quick agent consumption.

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 relatively simple tool with no output schema and only two parameters, the description is complete. It covers the action, the process, the output format, and the intended use cases. Given the richness of the annotations and schema, no critical information 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?

The input schema has 100% description coverage for both parameters (url and max_links). The description mentions 'any URL' and the output, but does not add meaningful semantic detail beyond the schema. The baseline of 3 applies because the schema already carries the parameter documentation.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the action (generate), the resource (llms.txt file), and the target (any URL). It distinguishes itself from sibling tools by emphasizing the output and indexing use case, making it clear this is about file generation, not analysis or checking.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context for when to use the tool. However, it does not mention alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the core safety profile. The description adds that it 'Returns the full joke text,' which is useful but does not disclose error behavior, rate limits, or other potential edge cases. This is consistent with the reduced burden when annotations are present.

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

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

The description is a single sentence, concise, and front-loaded with the verb and resource. Every word conveys essential information without redundancy, making it highly 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?

For a simple lookup tool with one parameter, full schema coverage, and comprehensive annotations (readOnly, idempotent, non-destructive), the description is complete. The existence of an output schema further reduces the need to explain return values. The tool's behavior is fully captured by the current description.

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

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

The input schema provides 100% coverage with a clear description for the single 'id' parameter ('The ID of the dad joke to retrieve'). The tool description does not add additional parameter semantics beyond what the schema already documents, 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 uses the specific verb 'Retrieve' and clearly identifies the resource as 'a specific dad joke by ID.' It distinguishes itself from siblings like random_joke and search_jokes by focusing on retrieval by ID, making its purpose immediately clear.

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

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

The description implies the appropriate use case: when you have a specific joke ID and want the full joke text. It does not explicitly name alternatives or provide exclusions, but the context ('by ID') gives clear guidance. Without explicit comparison to random_joke or search_jokes, it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful context: it scopes to 'caller's' subscriptions and specifies return fields plus the default of active-only. No contradictions, but it doesn't discuss potential edge cases like empty results or pagination; however, the annotations carry the safety burden.

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 with zero fluff. It front-loads the purpose, then lists return fields, then gives usage guidance. Every sentence earns its place and the structure 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?

For a simple list tool with one optional parameter, the description covers what it does, what it returns, and when to use it. The rich annotations cover side effects, and the description compensates for the lack of an output schema by listing the return fields. It is complete for the tool's complexity.

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

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

Schema description coverage is 100% for the only parameter ('include_inactive' with 'Include cancelled subscriptions in the response (default false)'), so the schema fully explains the parameter. The description adds minimal extra meaning beyond setting context with 'active subscriptions', matching the baseline 3 for high 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 states the action (List) and resource (the caller's active subscriptions), and lists the returned fields (id, type, params, etc.), making the tool's purpose concrete. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on read-only 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?

The description explicitly tells when to use it: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly implies the tool is for review and pre-cancel/id lookup, and indirectly contrasts with subscribe/unsubscribe alternatives.

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

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

Annotations are all false and unhelpful (readOnlyHint=false, etc.), so the description must bear the full burden. It does: explains the claim_token mechanism (filing without an account returns a token that can be passed later to read status), discloses rate limiting (5/day), pricing (free, no quota), and team response cadence (daily digests). 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?

While longer than some examples, every sentence earns its place. The description is front-loaded with purpose, then logically covers usage cases, exclusions, mechanics, and constraints. No redundancy or fluff; 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?

Despite no output schema, the description explains what to expect from filing (claim_token) and from later token use (status and resolution details). It covers scope, format, rate limits, and cost. For a 4-parameter, non-destructive feedback tool, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema: it demonstrates how to use claim_token ('pipeworx_feedback({claim_token:"pwfb_…"})'), explains what the token does (read whether fixed and what changed), and gives guidance on message specificity. This elevates it above baseline.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from siblings by focusing on feedback about Pipeworx tools, explicitly contrasting with tools from other MCP servers. This is a textbook clear purpose statement.

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

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

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and an explicit when-not-to-use (tools from other servers) with rationale ('we cannot fix it'). It also advises to describe issues in terms of Pipeworx tools and not to paste end-user prompts, offering strong decision support.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable context: caching delay (5min-1h), data provenance (CF analytics-engine), and privacy (no PII, just pack/tool/count). This goes beyond annotations without contradicting them.

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

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

The description is moderately sized but well-structured, starting with a hook, then outputs, use cases, and data characteristics. The numbered use cases make it easy to scan, and no sentences are wasted.

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

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

Despite having no output schema, the description sufficiently covers the return contents (top tools, top packs, call volume), the data source, caching behavior, and use cases. For a simple tool with one optional parameter, this is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances the 'window' parameter by explaining the trade-off: shorter windows surface current trends, longer show steady-state demand. This adds meaning beyond the enum values.

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

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

The description clearly states that the tool returns top tools, top packs, and total call volume over a recent window, with a specific verb ('Returns') and resource ('Pipeworx'). It distinguishes itself from siblings by mentioning 'what other AI agents are calling on Pipeworx right now,' which is unique among the listed 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 provides three explicit use cases, such as discovering hot data sources and confirming canonical tools, which guide when to use it. However, it does not explicitly mention when not to use it or name alternative tools like discover_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 read-only and non-destructive, but the description adds extensive behavioral detail: detection logic (monotonicity ordering, partition-sum ≈1, >3pp threshold), Jaccard similarity filter, placeholder filtering rule, response structure, and fill check pricing with explicit warning not to trade when realizable edge ≤0. 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 long but well-structured with clear sections for modes, filters, response, and fill check. Every sentence adds value, but it could be tightened without losing information. Overall appropriately sized for the tool's complexity.

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

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

Covers all aspects: both modes, default no-args behavior, detection thresholds, filters, response fields (opportunities[], partition_check), fill check semantics, and cross-reference to polymarket_fill_risk. With no output schema, the description effectively documents the return structure.

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

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

Schema coverage is 100% with both parameters described, but the description greatly enriches meaning by detailing what each mode does: event walks child markets and checks date/threshold ordering plus partition check; topic searches related events and flattens markets. It also explains no-args behavior, which the schema doesn't cover.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, with specific verbs and resource. It distinguishes its two modes (event vs topic) and even references a sibling tool (polymarket_fill_risk) for custom sizing, separating its own scope.

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 guidance: no args for trending_scan, event for specific markets, topic for cross-event scanning, and recommends event for a specific market. It explains when cross-event mode is advantageous and when not to trade based on fill check, plus names an alternative tool for custom sizing.

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

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

The description discloses numerous behavioral traits beyond the annotations: 1-hour KV-level caching keyed on knobs, diagnostics (_diagnostics with funnel counters, filter_skips), the logic behind each model family, the 24h-move warning, and the caveat on Fed signals. These add substantial context beyond readOnly/openWorld/idempotent hints and show no contradictions.

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

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

The description is long but densely structured, with clear section labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, RESPONSE TOP-LEVEL, TRADEABLE-EDGE KNOBS). Every sentence adds technical detail, but the sheer volume could be slightly pruned; still, it is far from wasteful and deserves a 4.

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, the absence of an output schema, and the rich input schema, the description goes above and beyond to explain the response structure (by_segment, fed_candidates/fed_note, _diagnostics), the logic for edge calculations, slippage handling, caching, and edge-case filters. It provides a complete mental model for correct invocation and interpretation.

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 strategic meaning for key knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly), especially the caveat that partition arbs always return kelly_fraction_half=0 and that min_partition_leg_kelly applies per-leg inside top_legs. This goes beyond the schema by explaining interaction effects.

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 ('Scan top Polymarket markets') and resource ('return opportunities where Pipeworx data disagrees with market price'), clearly distinguishing from sibling tools like polymarket_arbitrage or polymarket_edge_tracker. It also declares its intended use case ('what should I bet on today'), making purpose unambiguous.

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

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

The description provides clear context on when to use the tool ('Built for what should I bet on today — agents discover opportunities without paging hundreds of markets') and explains design choices (e.g., Fed bets excluded, concentrated_longshot rare-by-design). However, it does not explicitly contrast with sibling tools or state when not to use it, so it stops short of a 5.

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

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

Beyond the readOnlyHint and idempotentHint annotations, this description discloses extensive behavioral details: response structure (tracked[], expired[], snapshot_dates[]), data gaps due to cache-miss, 60-day TTL limitations, decay computed on |edge_pp_net| with sign explanation, and that values are daily closes not intraday. This goes far beyond basic 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 exceptionally well-structured: it opens with a succinct purpose, then proceeds through args, a detailed RESPONSE breakdown, and LIMITS. Every sentence carries meaningful information, and the bolded section headers (RESPONSE, LIMITS) aid scanning without 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?

With no output schema, the description fully explains the return value semantics, including the meaning of expired opportunities and 'median lifespan is your competition clock.' It covers parameter effects, data gaps, and historical limits, making it comprehensive for a read-only telemetry 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?

The input schema already provides 100% coverage for both parameters (days and window) with clear descriptions. The description's inline args line ('days (lookback, default 14, max 30), window (snapshot family, default '1wk')') mostly restates the schema without adding new semantic depth, so it neither compensates for nor exceeds the schema's baseline.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It defines the exact question it answers ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence/decay rather than current edges.

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

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

The description provides strong contextual usage guidance via the example of a 'fresh wide edge vs a 3-week-old wide edge,' implying when to use this tool for evaluating edge maturity. However, it does not explicitly name alternatives or state when NOT to use it, leaving a small gap in direct comparison to siblings.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds substantial behavioral context: it walks the order book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, and per-leg details. It also explains the risk of partial basket fills and forced directional risk, which goes far beyond the annotations. No contradiction with annotations; the description enhances understanding of side effects and output semantics.

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 carries critical information for two distinct modes. It is front-loaded with the core purpose and then structured into SINGLE-MARKET and BASKET sections, making navigation easy. It could be slightly more concise, but the density 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 the tool's complexity, no output schema, and rich annotations, the description fully compensates by enumerating return fields for both modes, explaining edge cases (thin legs, partial fills), and providing risk warnings. It covers parameters, outputs, use cases, and failure modes, making it complete for an agent to select and invoke correctly.

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

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

Although the schema covers all parameters, the description adds crucial semantic layers: it clarifies that market and event are mutually exclusive modes, explains side defaults per mode, and reinterprets size_usd as settlement notional in basket mode. It also lists outputs tied to parameters. This goes beyond the schema's basic descriptions, enriching the meaning of each 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 states a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges signals, explaining it is a pre-trade risk check for those tools. This is a precise, non-tautological purpose statement.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why: theoretical overround on thin books is not capturable and partial basket fills convert arb into unhedged directional positions. This is exemplary usage guidance with concrete thresholds and alternatives implied.

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/non-destructive annotations, the description discloses substantial non-obvious behavior: token-overlap matching, compatibility_codes[] semantics, the rule that unknown metric_type/match_subtype legs are never paired, the null meaning of temporal_alignment, the gross (fee-unmodeled) spread disclosure, and skipped/cross-type counters. These are exactly the behavioral details an agent needs before calling, and none contradict the annotations.

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

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

The description is front-loaded with a one-sentence overview and logically organized into modes, response, safety fields, codes, and fees. However, it is very long and somewhat redundant—`temporal_alignment_unknown` is explained twice, and the 'BOTH modes' point is repeated. It is structured but not concise, deserving a middle 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 carries the full burden of explaining return values, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility fields, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters are all covered. Nothing an agent needs to correctly invoke this tool 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?

The input schema already has 100% coverage, including descriptions and examples for `topic`, `kalshi_event_ticker`, and `polymarket_event_slug`, plus override semantics. The tool description reinforces the two-mode relationship and says both modes use the identical matcher, but it doesn't add much meaning beyond what the schema already provides. Baseline 3 is appropriate here.

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 precise verb+resource statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from same-venue arbitrage or edge tools by focusing on cross-venue comparison and naming both venues. The two modes are explicitly scoped, making the tool's function 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 provides clear mode selection: pre-mapped `topic` shortcuts vs explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings, and states both modes run the same matcher. It also adds a strong expectation-setting caveat that pre-mapped topics often return compatibility warnings and are not necessarily tradeable. However, it doesn't name sibling alternatives or state explicit when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety profile is covered. The description adds valuable context by naming the external source (icanhazdadjoke.com) and the exact return shape (joke text and ID), which goes beyond annotations.

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

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

The description is two short sentences with no filler. The key verb and resource are front-loaded, and every word adds meaning.

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

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

The tool is simple, has an output schema, and annotations cover safety. The description provides enough behavioral context (source, return values) to be fully understood without any 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?

There are zero parameters and the schema coverage is 100%, so the baseline is 4. The description adds no parameter-specific details, but none are needed since the tool takes no input.

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 the specific verb 'Fetch' and clearly identifies the resource: 'one random dad joke from icanhazdadjoke.com'. It also states the return values ('joke text and alphanumeric ID'), which distinguishes it from sibling tools like get_joke (specific joke) and search_jokes (search).

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

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

The description implies usage context: use this when you need a random dad joke. It does not explicitly name alternatives or exclusions, but the 'random' qualifier clearly separates it from search/get siblings, providing clear context without needing explicit contrast.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable context: the tool is scoped to the agent's identifier (anonymous IP, BYO key hash, or account ID) and that omitting the key lists all saved keys, which 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 two sentences, front-loaded with the primary action, and every sentence earns its place. It efficiently conveys purpose, usage, scoping, and related tools 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?

For a simple tool with one optional parameter, no output schema, and strong annotations, the description is complete. It covers the two modes of operation, scoping, and complementary tools, providing sufficient information for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context by giving examples of keys (target ticker, address, research notes) and clarifying the dual behavior when the key is omitted, enhancing the schema's description.

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

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

The description clearly states a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It distinguishes itself from siblings by referencing remember and forget, making its purpose unambiguous.

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

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

The description gives clear context: use it to look up previously stored context without re-deriving it. It also mentions pairing with remember and forget, but does not explicitly state when not to use it or name alternative tools beyond these companions.

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 explicitly discloses a side effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This contradicts the readOnlyHint=true annotation, which implies no state changes. Therefore, per the rubric, transparency scores 1 due to annotation 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 compact, front-loaded with the primary action, and every sentence adds value. It covers the return payload, filtering, mark_read side effect, and alternative access in five efficient sentences without unnecessary 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 the tool's moderate complexity (5 optional parameters, no output schema), the description covers the essential aspects: what is returned (source, citation_uri, event payload), filtering options, the mark_read behavior, and polling suitability. The schema covers parameter details, and annotations cover safety, so the description is sufficiently complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema by giving a concrete example for 'type' ('sec_8k'), specifying 'since' as an ISO timestamp, and explaining the behavior of mark_read. This elevates it to a 4.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Pull fired events from your subscription feed.' It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on the persisted feed of fired alerts, including field details and filtering.

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 on when to use the tool (polling, filtering by type/since, marking read) and even provides an alternative access method (GET registry.pipeworx.io/alerts.json). However, it does not explicitly contrast with sibling tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive. Description adds fallback behavior (GDELT→GNews), USPTO soft-fail due to API sunset, input format for `since`, and return structure. This significantly enriches behavioral expectations 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?

Opening with user-intent examples front-loads the purpose. Subsequent sentences compactly cover sources/fallbacks, date parsing, return shape, and the alternative tool — no filler. Dense but 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?

For a tool with three heterogeneous sources, fallback behavior, date grammar, and a structured return, the description covers all operational aspects: source fan-out, failure modes (USPTO sunset, GNews fallback), input formats, and return fields. No output schema exists, so the description carries that burden—and it does.

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 detailed descriptions for all three parameters. The tool description largely repeats the schema's guidance (ISO/relative for `since`, ticker/CIK for `value`), adding no new semantic content. Baseline 3 is fair.

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 concrete user-phrased queries and states it's a change feed for a company in a time window, fanning out to SEC, news, and USPTO. It explicitly contrasts with entity_profile, distinguishing it from a key sibling. Verb+resource+scope are specific.

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

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

Explicitly names entity_profile as the alternative for static profiles, and frames usage around temporal queries ('this week/month/quarter'). This is clear when-to-use guidance with a named alternative.

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

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

Discloses scoping (per-identifier), persistence behavior (authenticated persistent vs 24-hour anonymous), and storage format (key-value pair). This adds significant value beyond the annotations, which only provide safety hints. No contradiction with annotations.

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

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

Four sentences, each providing distinct information: purpose, when to use, storage/retention semantics, and complementary tools. No redundancy, and the core action is front-loaded in the first sentence.

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

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

For a simple two-parameter storage tool, the description covers purpose, usage, scoping, persistence, and complementary operations. No output schema exists, so return values need not be explained. The schema handles parameter validation, making the description contextually complete.

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

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

Schema already provides strong descriptions for both parameters (100% coverage). The description adds contextual meaning by framing them as a 'key-value pair scoped by your identifier' and by giving use-case examples that illustrate what to store. This slightly elevates it above the baseline.

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

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

The description clearly states the tool saves data for later reuse, with a specific verb ('Save') and resource ('data'). It distinguishes from siblings by naming recall and forget for retrieval and deletion, and provides concrete examples of use cases.

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 ('when you discover something worth carrying forward') and gives concrete examples. It also names alternatives ('Pair with recall to retrieve later, forget to delete'), making usage boundaries unambiguous.

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?

Even with readOnlyHint, idempotentHint, and destructiveHint annotations present, the description adds substantial behavioral context: it cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, returns figi_candidates instead of asserting when a name is ambiguous, labels identifier provenance, and reports unresolved IDs explicitly rather than omitting them. This goes well beyond the annotation surface.

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 clause earns its place: examples are front-loaded, SUPPORTED TYPES and caveats are visually scoped, and the graceful-degradation sentence conveys a behavior that would otherwise require a live call to discover. It reads dense rather than padded.

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 no-output-schema tool with only two parameters, the description tells the agent what will come back (canonical IDs, source labels, figi_candidates, unresolved list, RxCUI/ingredient/brand/citation), how to handle ambiguous matches, what to avoid in value, and how failures degrade. No critical invocation information 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%, yet the description still adds meaning: it explains the type enum semantics for company and drug, gives accepted input forms for value, supplies concrete examples ('AAPL', '0000320193'), and warns that bond issuer names must be passed exactly as printed without trailing security-class words. That is true added value beyond the schema.

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

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

The description opens with concrete user phrases and a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It enumerates exactly what is resolved (CIK, LEI, ticker, RxCUI, FIGI) and explicitly frames itself as the identification step ahead of sibling profile/comparison tools, so it is readily distinguishable from entity_profile and compare_entities.

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

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

'Use FIRST whenever you have a name but need an ID' is an explicit trigger condition and precedence rule, and the supported-types section clarifies when company vs drug resolution applies. It never names a sibling for the inverse case (e.g., already have an ID and want a profile), so it stops one step 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.

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive behavior. The description adds valuable context by revealing that it internally calls ai_visibility_check for each entity, ranks by score, and returns specific fields (score, confidence, signal density). This goes beyond annotations without contradicting them.

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

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

The description is four sentences, front-loaded with the core purpose, followed by mechanism, use case, and output. Every sentence adds distinct value (what, how, why, result) without unnecessary repetition. It's compact yet informative.

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

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

Given the lack of an output schema, the description appropriately explains the return format (ranked list with score/confidence/signal density). It also covers the probing mechanism and use case. The schema covers parameter ranges and defaults, so overall completeness is high, though it could briefly mention the 2-8 entity constraint or model selection in the description itself.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces entity semantics ('your brand + N competitors') but does not add new parameter details beyond what the schema already documents. The schema itself covers entity ordering and optional models/context, so no additional compensation is needed.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'), clearly distinguishing it from the single-entity sibling ai_visibility_check. It also names the internal mechanism (probing with ai_visibility_check) and output (ranked list), leaving no ambiguity about the tool's function.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an illustrative query, effectively conveying when to use the tool. It doesn't explicitly name alternative sibling tools or state 'use this instead of ai_visibility_check', but the 'side-by-side' comparison implies multi-entity scenarios, giving sufficient context.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses fan-out behavior across external APIs, potential slow first measurement (5-30s), and graceful degradation via sources_failed. These are meaningful behavioral traits not captured by the annotations, and nothing contradicts the declared 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 longer than typical but every sentence carries substantive information: purpose, sources, use cases, return structure, ecosystem scope, and failure behavior. It is front-loaded with the main purpose and follows a logical flow, though it could be trimmed slightly without losing meaning.

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

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

Given no output schema, the description thoroughly details the return value (summary block fields, per-advisory detail, links, alternative versions), the NPM-only scope, and partial-failure behavior. It fully equips an agent to predict outcomes and handle edge cases, making it highly complete for a composite tool of this complexity.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description reiterates that package is an npm name and version defaults to latest, but adds only minor context (e.g., scoped packages accepted) which is already present in the schema. No additional semantic depth is provided beyond what the schema already states.

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 composite purpose ('should I add this npm package to my project' check in ONE call) and enumerates exactly what sources and metrics are aggregated (deps.dev license/advisories/version history, bundlephobia bundle size/dependency count/ESM/tree-shake). This clearly distinguishes it from sibling tools like scan_competitor_ai_presence and deps.dev:version.

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 trigger language is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states the ecosystem boundary (NPM only in v1; other ecosystems go directly to deps.dev:version), providing a clear alternative path and when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds only that it returns 'matching jokes with IDs and text,' which is a minor behavioral detail. It does not disclose any additional constraints (e.g., pagination, ordering, or filtering nuances) beyond what annotations and the schema already 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 two short sentences, each earning its place: the first states the action, the second states the output. There is no redundant information or filler. It is efficiently front-loaded and easy to scan.

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

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

For a simple search tool, the description is complete. The output schema exists, so return values are documented elsewhere. Annotations cover the operational safety (read-only, idempotent). The tool has only two parameters, both self-explanatory via the schema. No additional context (e.g., authentication, rate limits) is needed for this straightforward read operation.

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 has 100% parameter description coverage: both 'query' and 'limit' are described. The description's phrase 'by keyword or topic' essentially rephrases the 'query' parameter without adding new meaning. Since the schema carries the full semantic weight, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Search dad jokes by keyword or topic.' The verb 'search' combined with the resource 'dad jokes' is specific, and the output of 'matching jokes with IDs and text' clarifies what is returned. This implicitly distinguishes it from sibling tools like 'get_joke' (retrieve a specific joke) and 'random_joke' (get a random joke), making the purpose unambiguous.

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

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

The description clearly conveys the tool's context: use it to find jokes based on a keyword or topic. However, it does not explicitly mention alternatives or exclusions (e.g., 'for a specific joke, use get_joke'). The verb 'search' provides enough contextual cue for when to use this tool, but without explicit sibling differentiation, it stops short of a 5.

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

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

Even with annotations (readOnly, openWorld, idempotent, non-destructive), the description adds rich behavioral detail: it returns 'character offsets and similarity scores,' uses 'BGE-base-en embeddings + cosine over 500-char overlapping windows,' and discloses the '200K chars cap (longer inputs are truncated and flagged).' This goes well beyond the annotations and gives the agent concrete expectations about output and failure modes.

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

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

The description is dense but every sentence earns its place: it explains the operation, the use case, the pairing, and the technical implementation in three sentences. It front-loads the core action and then adds necessary context. There is no filler 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?

The tool has 3 parameters and no output schema, but the description covers all essential context: what input to provide (already-fetched text), how the algorithm works (embeddings, windows), what output to expect (passages with offsets/scores), and the truncation limitation. It also addresses the workflow with a sibling tool. This is fully complete for an agent to decide whether and how 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 coverage is 100%, so the baseline is 3. The description reinforces the text parameter ('text you already pulled') and the query parameter ('natural-language query') but does not add new meaning beyond what the schema already provides. It does not explain the limit parameter beyond the schema, but the schema itself is fully descriptive, so 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+resource: 'Semantic search INSIDE a fetched record,' which clearly states what the tool does. It distinguishes from siblings by emphasizing 'inside a fetched record' and contrasting with 'ask_pipeworx_grounded' (fetch with the gateway, then ground over relevant passages). The scope is unambiguous.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt,' and provides a concrete alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' It also implies when not to use it (when the text fits in the prompt) and names a sibling tool, giving clear decision context.

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

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

Annotations indicate a non-read-only, non-destructive, idempotent operation. The description adds critical context: OAuth requirement (anonymous can't persist), delivery channel behaviors (feed always on, email/SMS optional), phone verification constraint, and webhook auto-disable after 10 consecutive failures. It also discloses return of subscription id and one-time webhook secret, going well beyond the annotation hints.

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

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

While longer than average, every section serves a purpose: core creation, requirements, type catalog, and delivery details. Information is packed into structured clauses and examples. It could be slightly trimmed, but there is no fluff or redundant wording.

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 (nested params, multiple types, delivery channels, no output schema), the description covers prerequisites, type-specific filters, return behavior (subscription id, one-time webhook secret), and operational details (auto-disable). It is a self-contained description that leaves no critical gaps.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds semantic value by explaining type-specific parameters, e.g., items:["5.02"] as officer change, and providing concrete examples for each subscription type. It also clarifies delivery constraints (SMS must match verified phone, 10/day cap) that enrich the schema, making it more than repetition.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This uses a specific verb (Create) and identifies the resource (subscription to event stream) with clear scope. It also distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation, and enumerates supported types, leaving no ambiguity.

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

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

The description states this is for proactive monitoring and contrasts with pulling via recent_alerts or GET registry.pipeworx.io/alerts.json, implying subscription is for push-based monitoring. It also requires a Pipeworx OAuth account, clarifying prerequisites. It doesn't explicitly list when not to use, but provides clear context and alternatives.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds context about return shape (category-bucketed example questions with tool+argument shape) and that it comes from a live catalog, which is useful beyond the annotations. No contradiction, but it doesn't disclose any limitations or failure modes.

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 ideal, but it is well-structured: leading with example user questions, then describing the output, then call variants and usage priority. Every part earns its place for an onboarding tool, though it could be tightened slightly.

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 a single optional parameter, no output schema, and strong annotations, the description leaves nothing important uncovered. It explains what the agent gets, how to use it, and when to use it, making it highly complete for the tool's simple nature.

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 single optional 'topic' parameter with 100% coverage. The description adds valuable context by showing example values ('finance', 'pharma', 'betting') and explaining the omit-for-full-spread behavior, going beyond mere schema repetition.

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

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

The description clearly states the tool's function: it is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shapes. It distinguishes itself from siblings by explicitly mentioning 'meta-tools' and positioning itself as the first stop, which separates it from ask_pipeworx and discover_tools.

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

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

The description gives explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also specifies call patterns: no arguments for full spread, or pass topic to focus, with a list of example topics.

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, it discloses that the row is deactivated rather than deleted, explaining the non-destructive behavior and its impact on historical data. Ownership enforcement is also a behavioral detail not present in annotations, adding meaningful 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?

Three sentences cover purpose, ownership, and deactivation behavior with no extraneous words. Each sentence adds distinct, necessary information, and the main action 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 simple one-parameter tool, the description covers the action, constraint, and side effect on historical data. Annotations and schema handle safety and parameter details, leaving no critical gaps.

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

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

The schema already fully describes the id parameter (uuid returned by subscribe). The description adds the semantic constraint that the id must belong to the user's own subscription, clarifying valid input 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 'Cancel a subscription by id,' which clearly states the verb (cancel), resource (subscription), and how it's identified (id). It distinguishes from sibling tools like subscribe and list_subscriptions by specifying the cancel action and the deactivation behavior.

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 a when-not condition: 'you can only cancel your own subscriptions,' clarifying the ownership boundary. It also mentions that historical events remain available via recent_alerts, offering an alternative for post-cancellation access to related data.

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?

Even with annotations already indicating read-only and idempotent behavior, the description adds crucial operational context: the meaning of each verdict, especially the distinction between 'could_not_verify' (check did not happen, must not be used as evidence) and 'unsupported' (no source covers it). It also discloses the verification pipeline, error handling, and the guarantee of verbatim evidence with citations.

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

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

The description is dense but well-structured: it opens with trigger phrases, defines the use case, explains routing, lists verdicts, and adds a warning about a specific error case. It is longer than minimal but every section carries meaningful information. Slightly verbose in the middle but 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?

With no output schema, the description needs to explain return values and edge cases, and it does. It covers the verdict list, the evidence/citation format, the meaning of error states, and the routing logic across claim types. This is complete for a tool of this complexity, even including caller guidance about 'could_not_verify'.

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 100% coverage for both parameters (claim and tolerance_pct) with clear descriptions. The tool description adds some context about exact percent-delta math and the default tolerance cap, but does not substantially enhance the parameter-level meaning beyond what the schema already states. This matches the baseline of 3 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 natural-language claim verifier that returns verdicts like confirmed/refuted, with specific verbs ('fact check', 'verify the claim') and a resource ('authoritative sources'). It distinguishes itself from sibling tools by describing a fast path for company-financial claims and a grounded fallback for other factual claims, plus a note that it replaces 4–6 sequential calls.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance for financial vs. other claims. However, it does not explicitly name alternative sibling tools or specify when NOT to use this tool in favor of another, so it falls just short of a 5.

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