Madrid Events

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond this: the default model is free, the optional Anthropic probe uses a BYO key and incurs direct charges, and the return shape includes per-model score, confidence, signals, and raw_response. This gives a clear behavioral picture without contradicting annotations.

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

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

The description is compact and front-loaded, with the core action and output in the first sentence. The second sentence covers behavioral details (model defaults, BYO key) and return structure, and the final clause lists use cases. Every sentence earns its place; no filler.

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

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

With no output schema, the description appropriately explains the return format (per-model object plus combined view). It also covers default model behavior, optional Anthropic integration, and relevant use cases. It could mention what 'signals' represents or potential rate limits, but the core functionality is well covered for a read-only probe tool.

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

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

Schema coverage is 100%, so each parameter is described in the schema. The description adds extra semantic value by explaining that 'models' can be omitted to use just the free default, and that '_apiKey' is only needed for Anthropic. This clarifies relationships between parameters beyond what the schema provides.

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

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

The description uses an explicit verb ('Probe') and specifies the resource (LLMs) and the exact output (visibility score 0-100 per model). It also clearly distinguishes this tool from siblings by focusing on AI visibility scoring rather than general Q&A or research, and mentions specific use cases like AI-marketing audits.

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 usage context ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and guidance on model selection (default Workers AI free, optional Anthropic with BYO key). It lacks explicit alternatives or when-not-to-use statements, but the context is strong enough to guide an agent.

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

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

The description adds substantial behavioral context beyond the annotations: it returns citations (pipeworx:// URIs), routes to appropriate sub-tools, works on every tier, and is described as 'one fast call'. It also specifies domains covered (e.g., SEC filings, FDA, FRED/BLS) and notes it handles breaking news. This goes beyond the safe-read/idempotent hints already provided, enriching the agent's understanding of what to expect. No contradiction with annotations.

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

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

The description is longer than typical, but every sentence serves a purpose: it includes a strong preference directive, domain list, routing explanation, examples, and step-up alternatives. The structure is front-loaded with the most important guidance and then expands logically. While it could be trimmed slightly, it is not wasteful or redundant.

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 broad scope, the description is remarkably complete. It covers what the tool does, when to use it (and when not), how it works (routing, citations), what kinds of questions are appropriate, and how it relates to siblings. The schema is simple (one required param), annotations provide safety profile, and output schema is absent, so the description carries the full burden — which it meets thoroughly.

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

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

Schema description coverage is 100%, with all six parameters being aliases for the single 'question' parameter, each with a clear description. The description itself does not add new parameter-level details beyond the schema, but it does provide examples and context for the kind of questions to pass. Since the schema already fully documents the parameters, a 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 purpose: it routes questions to one of 5,529 tools across 1455 sources and returns structured answers with citations. It uses specific verbs like 'routes' and 'returns' and explicitly distinguishes the tool from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different needs.

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

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

Usage guidance is explicit and actionable. The description says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and provides clear conditions for stepping up to ask_pipeworx_grounded (hallucination-resistant single answer) or deep_research (broad/multi-part questions). It also lists example queries, making it easy for an agent to decide when to use this tool.

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

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

Beyond the annotations, the description adds critical behavioral context: it is a beta with experimental routing candidates that may be active, currently no candidate is active so it matches ask_pipeworx exactly, and it does not fall back to anything — it is a fully functional router. This transparency exceeds what annotations convey.

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

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

The description is compact yet information-dense, spanning just two sentences. It front-loads the beta status and immediately shares the key facts: identical router, candidate routing, current status, usage instruction, and fallback behavior. Every sentence earns its place.

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

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

For a complex meta-router with no output schema, the description is remarkably complete. It explains the experimental nature, current state, usage equivalence to ask_pipeworx, and the comparison process, enabling an agent to select and invoke the tool correctly without needing additional context.

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

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

Schema coverage is 100% with clear descriptions of the 'question' parameter and its aliases. The description does not add parameter-specific guidance, but since the schema fully covers semantics, 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 it is a beta universal router identical to ask_pipeworx with the same 5,529 tools, arguments, and response shape, while distinguishing itself by mentioning candidate routing improvements. This gives a specific verb+resource with clear differentiation from the sibling tool.

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

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

It explicitly tells the user to use it exactly like ask_pipeworx when they want the newest routing, and explains that results are compared against the stable router. It also notes that it is a full working router with no fallback, providing sufficient context for when to use this tool versus the stable alternative.

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

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

Discloses extensive behavioral context beyond annotations: extraction is strictly limited to tool result, return format includes verbatim evidence and confidence, refusal reasons are enumerated, and it notes one extra LLM call overhead. Annotations (readOnly, idempotent) are consistent, and the description adds value without contradiction.

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

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

The description is compact yet dense, covering purpose, process, output schema, usage boundaries, and cost in a structured flow. It front-loads the main purpose and uses clear separators (success vs refusal) without unnecessary fluff, earning a high but not perfect score due to its length.

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

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

Given the tool's complexity (routing across thousands of tools, extraction, refusal handling), the description is remarkably complete. It specifies the exact return structure in prose, all refusal reasons, high-stakes use contexts, and cost tradeoffs, making it self-contained even without an output schema.

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

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

The schema fully describes the parameter (question and its aliases) with 100% description coverage, so the description does not need to add more. The tool description's process overview implies the question is natural language but adds no specific parameter details beyond the schema, aligning with the baseline 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 identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and explains its distinct behavior: routing to the best tool, fetching data, and extracting the answer only from the tool result. It differentiates from sibling ask_pipeworx by the extraction step and explicit refusal behavior, making the purpose specific and distinguishable.

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 specifies when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also gives an alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost difference, providing clear selection guidance.

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

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

The description is exceptionally transparent about behavior beyond annotations: it details fan-out to category-specific data packs, parallel execution, resolver contract with confidence levels, short-circuit statuses (low_confidence_match, market_closed_or_inactive), tradeability warnings, fallback mechanisms for news (GDELT 429s), and cancellation-rule risk. Annotations already declare readOnly/idempotent, but the description adds extensive operational context.

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

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

The description is long but well-organized with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) and front-loads the core purpose. Every section provides specific, actionable guidance; there is no padding. It is not as concise as a two-sentence description, but the density and structure justify its length.

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

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

With no output schema, the description carries full responsibility for explaining return values, and it does so thoroughly: result.market, result.analysis, result.evidence, resolver contract fields, parent_event structure, news field fallback flags, and status codes. It also covers edge cases like closed markets and wide-spread markets. The description is highly complete for a 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% with descriptions and examples for all three parameters, so the baseline is 3. The description adds value by explaining the classifier taxonomy and fan-out examples that clarify what types of market inputs are accepted and how they are interpreted (e.g., BTC bet → coingecko + fred + gdelt+gnews). This goes beyond the schema's basic property descriptions, though it is more about behavioral outcomes than parameter syntax.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' – a specific verb (research), resource (Polymarket bet), and method (pulling Pipeworx data). It lists concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), and distinguishes itself from siblings by focusing on single-market evidence synthesis rather than edge-finding or arbitrage 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 use cases and safety guidance: 'Use for should I bet on X...' and 'ALWAYS inspect these [market_match_confidence] before trusting the analysis block.' It also warns to 'Check this before sizing sports/esports/event-occurrence bets.' However, it does not explicitly compare to sibling alternatives (e.g., ask_pipeworx or polymarket_edges), so exclusion guidance is missing.

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 data sources (SEC EDGAR/XBRL and FAERS), specifics like off-calendar fiscal year handling, and that results are sorted by primary metric. It also mentions citation URIs, adding behavioral context not present in annotations.

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

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

The description is longer than ideal but front-loaded with trigger phrases and the core purpose. Every sentence contributes functional detail, such as data sources, sorting, and replacement value, but the density makes it slightly less concise than a 5.

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

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

Even without an output schema, the description explains what the response contains (paired data, citation URIs, sorted results) and the data types involved. It addresses all essential aspects for invoking the tool correctly, especially given the rich annotations.

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

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

The input schema already covers both parameters with 100% coverage, but the description adds significant meaning by explaining what each type ('company' vs 'drug') retrieves and providing concrete examples for values. This goes beyond the schema's minimal descriptions, though the schema remains the primary reference.

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

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

The description is explicitly action-oriented: "side-by-side comparison of 2–5 companies or drugs in ONE parallel call," with trigger phrases like 'X vs Y' and 'rank these companies.' It clearly distinguishes itself from sibling tools like entity_profile by focusing on multi-entity comparison.

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

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

The description explicitly states "ALWAYS PREFER over sequential single-pack lookups when comparing entities," giving a direct when-to-use instruction. It also notes that it replaces 8–15 sequential lookups, reinforcing the preference and implying when not to use it.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavioral context: account/plan requirements, internal parallel routing to 5,529 tools, the findings packet structure (verbatim evidence + confidence + gaps[]), contradiction detection for standard/thorough, semantic excerpting behavior, and expected latency (15-90s). No contradiction with annotations.

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

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

The description is verbose but logically structured, front-loading the critical account requirement and then moving from purpose to usage context, behavior, and performance. While every sentence earns its place, some clauses are convoluted (e.g., the long parenthetical on citation_uri), and the length could be trimmed without losing essential details.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers the return format, gaps[] behavior, contradictions[], citation resolvability, semantic excerpting, latency expectations, and clear alternative tools. An agent has enough information to invoke this tool correctly and understand what will come back.

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 schema already carries the heavy lifting. However, the description adds useful nuance: it explains what depth levels do in practice (quick=3 facets, standard=5 + gap recovery, thorough=8 + iterative hop) and emphasizes that question can be broad/multi-part. This adds meaning beyond the raw schema.

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

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

The description clearly states a specific verb+resource combination: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in ONE call. It explicitly distinguishes itself from open-web search and from the sibling ask_pipeworx, making its scope unambiguous.

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

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

The description provides explicit when-to-use guidance ('best for broad/multi-part questions over structured data') and when-not-to-use guidance ('For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It names the alternative tool and explains the difference in routing, making it easy for an agent to choose correctly.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context by explaining the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also disambiguates that results are directly callable and no second lookup is needed, 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 front-loaded with the core purpose, then provides a domain list, return behavior, and usage rule. It is concise, well-structured, and every sentence contributes meaning. No redundancy or filler.

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

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

For a simple discovery tool with one required parameter, the description fully explains when to use it, what it returns, and why it is useful ('no second schema lookup needed'). There is no output schema, but the description compensates by describing the result structure. The annotations and schema together provide a complete picture.

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

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

Schema coverage is 100% for the query parameter and its aliases. The description adds context about the query being a natural language description, but this is already captured in the schema. The description does not explain 'limit' beyond what the schema states, so it adds minimal parameter-specific value beyond the structured fields.

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

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

The description states the tool's function clearly: 'Find tools by describing the data or task.' It is a specific verb+resource (discover tools) and distinguishes itself from siblings by serving as a meta-search over all available tools. The scope is well-defined with an explicit list of domains (SEC filings, financials, FDA drugs, etc.).

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 when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly sets expectations for when this tool is appropriate versus directly calling a specific tool.

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

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

The description goes well beyond the readOnly/idempotent/openWorld annotations, revealing that it fans out across multiple sources in parallel, returns specific fields (with URIs and sorting), soft-fails for patents due to API sunset, and uses a GDELT→GNews fallback. No contradictions with annotations.

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

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

The description is dense but overlong, opening with seven redundant user-phrasing examples before reaching the core definition. While the later details (output fields, fallbacks) are valuable, the opening could be tightened without losing meaning.

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

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

Despite having no output schema, the description fully inventories the return payload (CIK, filings with pipeworx URIs, fundamentals with sorting, patents with sunset note, news fallback, LEI) and covers input constraints and failure modes. This is comprehensive for a 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?

The schema already provides 100% coverage for both parameters, including ticker/CIK examples and the 'names not supported' restriction. The description duplicates this information without adding new parameter-level semantics, so it does not exceed the baseline for full schema coverage.

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

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

The description defines a 'full cross-source profile of a US public company in ONE parallel call' and enumerates the specific data fields returned (CIK, filings, fundamentals, patents, news, LEI). It is clearly distinguished from sibling tools by emphasizing its holistic, single-entity nature and its preference over chaining individual 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?

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides a direct alternative: 'use resolve_entity first if you only have a name.' This gives clear when-to-use and when-not-to-use guidance, including a fallback for unsupported inputs.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: the default temporal scope (next ~100 days), the Spanish content, and the specific return fields (venue, address, geo, audience, price). No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the primary purpose, and contains no filler. Every sentence adds informational value, 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 read-only search tool with complete schema descriptions and strong annotations, the description adequately covers scope, filters, output fields, and language. No output schema exists, but the description explicitly lists the return fields, making it self-contained.

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

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

Schema description coverage is 100%, with each parameter fully described. The description only summarizes filters (keyword, free admission, date window) without adding syntax or format details beyond the schema, so it meets the baseline of 3.

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

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

The description uses a specific verb 'Find' with a clear resource: 'cultural events & activities in Madrid, Spain (next ~100 days)'. It distinguishes this tool from sibling tools, which are all research or subscription-related, by uniquely targeting events in Madrid.

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: geographic scope (Madrid), time horizon (next ~100 days), and filter options (keyword, free admission, date window). It does not explicitly state when not to use it or list alternatives, but no sibling offers similar functionality, so the guidance is adequate.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' is consistent. It adds minimal extra behavioral context beyond confirming what is destroyed (the memory identified by key), but does not disclose irreversibility, side effects, or permissions. This is adequate given annotation coverage, but not rich.

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

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

The description is a single sentence with an active verb and clear resource, followed by concise when-to-use guidance and related tool names. No wasted words, and the structure is effective.

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

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

This is a simple tool with one parameter and no output schema. The description covers purpose, usage context, and parameter scope; annotations cover safety behavior (destructive, idempotent). Nothing else is needed for an agent to invoke this 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%: the property 'key' is described as 'Memory key to delete.' The description repeats this ('by key') without adding new meaning or examples beyond what the schema provides. Baseline 3 applies when schema fully documents parameters.

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

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

The description clearly states the action ('Delete a previously stored memory by key') and identifies the resource (memory key). It also distinguishes from siblings by naming 'remember' and 'recall' as complementary tools, which helps differentiate the deletion operation from storage and 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 lists when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references related tools ('Pair with remember and recall'), providing guidance on how the tool fits within a workflow.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds behavioral details: fetches the page, extracts title/description/key links, and emits a single text blob in standard llms.txt format. This goes beyond the annotations and gives insight into the process without conflicting with 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 three sentences: purpose, mechanism, and use cases. It is front-loaded with the core action, and every sentence adds value without unnecessary fluff, making it highly concise and well-structured.

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

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

The description covers what it does, how it works, and the output format. Annotations provide safety and idempotency, and even without an output schema, the description sufficiently explains the return value as a single text blob. For a simple read-only tool, this is complete and actionable.

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 covers both parameters (url and max_links) with complete descriptions, so the baseline is 3. The description does not add additional parameter-specific semantics, such as how max_links affects output or how the URL is processed, so it stays at 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 generates an llms.txt file for any URL, specifying the verb 'Generate', the resource 'llms.txt file', and the purpose 'so AI crawlers can index the site cleanly'. It distinctively separates from siblings by also mentioning auditing a competitor's AI visibility, but still focuses on the unique output of the tool.

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 concrete use cases: getting a client's site indexed, drafting for own project, or auditing a competitor's AI visibility. However, it does not explicitly name alternative tools or provide exclusions, stopping short of a 5 which requires explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds context beyond the annotations by listing the exact return fields and specifying the scope ('caller's active subscriptions'), which helps the agent understand what data will be retrieved. It does not contradict the annotations.

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

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

Two sentences, front-loaded with the purpose and return fields, followed by use cases. Every sentence earns its place with no filler or redundancy. Excellent conciseness.

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

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

For a simple list tool with one optional parameter, no output schema, and strong annotations, the description covers the purpose, scope, return fields, and use cases. The only missing piece is the 'include_inactive' parameter, but the schema fully documents that. The description is complete for the agent to select and invoke the tool correctly.

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

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

The schema covers 100% of the parameter description ('Include cancelled subscriptions in the response (default false)'), so the description doesn't need to explain the parameter. The description adds no extra meaning about the 'include_inactive' parameter, but given high schema coverage, the baseline of 3 is appropriate. It does mention return fields, which is not parameter semantics but adds some context.

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

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

The description starts with a specific verb and resource: 'List the caller's active subscriptions.' It also specifies the return fields (id, type, params, etc.), making it clear what the tool does. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

The description gives explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies when to use it relative to subscribe/unsubscribe, though it doesn't explicitly name those tools or state when not to use it. The alternatives are implied but not directly named.

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

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

Beyond annotations, the description discloses key behaviors: filing without an account returns a claim_token for later lookup, rate-limited to 5 per identifier per day, free and doesn't count against tool-call quota, and the team reads digests daily. This gives the agent a complete picture of side effects and constraints. No contradiction with annotations.

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

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

The description is appropriately sized for the tool's complexity, with every sentence earning its place. It is front-loaded with purpose and structured logically: purpose, use cases, exclusions, claim_token flow, and rate limits. No fluff or redundancy.

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

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

Given the tool has no output schema, the description fully covers the response behavior (returns claim_token, later read status/changes), usage scenarios, exclusions, and constraints. It is complete enough for an agent to select and invoke the tool correctly without additional context.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds practical value beyond the schema. It instructs to "Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt," which clarifies the expected content of the message parameter. It also demonstrates usage of claim_token with an example call syntax, which is not fully captured in the schema description.

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

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

The description clearly states the tool's purpose: "Tell the Pipeworx team something is broken, missing, or needs to exist." It uses a specific verb and resource, and distinguishes itself from sibling research tools by focusing on feedback reporting. The scope is clarified by restricting to tools served by this Pipeworx connection, making it 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?

Explicit when-to-use guidance is provided: "Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)." It also states when NOT to use it ("if the tool came from a different MCP server ... file it with that server instead"), giving clear alternatives and exclusions.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it discloses the data source ('derived from CF analytics-engine'), privacy (no PII), output shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). These details go well beyond the annotations, and there is 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 front-loaded with the core purpose, then lists concrete use cases, then provides technical details about data and caching. Every sentence earns its place and there is no fluff or repetition. It is appropriately sized for the tool's simplicity.

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 one-parameter tool with no output schema and strong annotations, the description covers all necessary ground: what it returns, the data shape, the lack of PII, and caching behavior. An agent would know exactly what to expect and how to use it, even without examples or return type documentation.

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

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

The schema describes the single 'window' parameter with an enum and detailed semantics ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). Since schema coverage is 100%, the description doesn't need to do heavy lifting. It mentions the window values in passing but adds no new information beyond the schema, so a baseline 3 is appropriate.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window'. It uses specific verbs ('returns') and a resource ('what other AI agents are calling on Pipeworx right now'), and it distinguishes itself from sibling tools by emphasizing it's an aggregate/trending signal rather than a query tool.

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: 'discovering what data sources are hot', 'confirming a popular tool is the canonical choice before asking your own question', and 'seeing whether your use case aligns with what most agents need'. It gives clear context for when to use it, though it does not mention when not to use it or explicitly reference alternatives by name, so it falls short of a perfect 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 and destructiveHint=false, but the description adds substantial behavioral detail: the partition filter drops placeholder slugs, the fill check prices against live CLOB depth, and it warns 'do not trade it' when realizable_edge_pp ≤ 0. This exceeds the minimal annotation context.

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

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

The description is long but front-loaded with the core purpose and organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Each sentence contributes to understanding the tool's complex behavior, though the overall length is at the upper end of acceptable.

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

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

With no output schema, the description compensates by outlining the response structure ('opportunities[]', 'partition_check'), explaining the fill check, and covering edge cases like skipped_low_similarity and placeholder filtering. It is complete for a complex arbitrage 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?

Even though schema coverage is 100%, the description enriches both parameters with real examples ('fed-decision-may-2026'), notes that full Polymarket URLs are accepted, and explains the internal logic of event vs. topic modes. This adds significant meaning beyond the schema.

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

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

The opening sentence explicitly says 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', which identifies the exact verb, resource, and method. It clearly distinguishes itself from sibling tools like polymarket_edges or polymarket_fill_risk by focusing on arbitrage detection.

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 call modes: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names a sibling tool ('For custom sizing use polymarket_fill_risk'), giving clear guidance on when to choose an alternative.

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

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

Despite annotations (readOnlyHint, idempotentHint, destructiveHint) already covering the safety profile, the description adds rich behavioral detail: caching at KV level, slippage handling, Kelly capping at 0.25, diagnostics for empty segments, and a 24h-move warning. It fully discloses response structure and filters without contradicting annotations.

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

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

The description is long but well-structured with clear section headers (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loads the purpose. It is dense and not concise, but the complexity of the tool justifies the length; every section adds necessary operational detail.

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

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

With no output schema, the description thoroughly covers response segments, per-opportunity fields, diagnostics, and edge-case handling (e.g., Fed bets exclusion). It also documents knobs' effects and caching. The tool is highly complex, and the description leaves no critical operational gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: explains why knobs exist (e.g., 'drop opportunities where edge isn't realizable'), clarifies the subtle interaction between min_partition_leg_kelly and min_kelly, and describes the role of slippage. This goes beyond the schema's literal parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs and resources, and distinguishes itself from siblings by targeting daily opportunity discovery with a response organized by model families. The 'Built for' phrase explicitly frames the use case.

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 when-to-use context ('what should I bet on today') and explicitly excludes Fed bets with explanation, but does not name alternative tools for other cases. It provides enough context for an agent to know when to invoke it without explicit 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses crucial behavioral details: the response structure (tracked[], expired[], snapshot_dates[]), the sign convention for edge_pp_net (negative = SELL YES), the computation basis (daily closes, net of default slippage), and the storage limits (60-day TTL, snapshot enabled time). This greatly exceeds what annotations alone convey.

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

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

The description is dense but well-organized: a lead question, then a RESPONSE section enumerating output fields, and a LIMITS section. Every sentence adds value, with no filler. The structure makes the long description easy to parse.

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?

Since there is no output schema, the description fully explains the return values: tracked[] with time-series, trend, and decay metrics; expired[] with lifespan; and snapshot_dates[] with gap semantics. It also covers data freshness and historical limits. For a telemetry tool with 2 optional params, 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% with both parameters described in the input schema. The description mostly repeats the defaults and window families ('days ... default 14, max 30', 'window ... default 1wk') without adding new semantic meaning. It does not explain how parameters interact with response data beyond mentioning lookback, so it meets the baseline but adds little extra.

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

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

The description opens with a clear, specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and poses the exact question it answers: 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling tools like polymarket_edges by focusing on time-series decay rather than current edge values.

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 guidance through the distinction between 'a fresh wide edge and a 3-week-old wide edge' being 'different trades', implying this should be used when edge age or decay matters. It also clarifies snapshot gaps via cache-miss behavior. However, it does not explicitly name sibling alternatives or state 'use X when Y'.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Beyond these, the description discloses specific behaviors: walking the order-book ladder, returning detailed metrics (top_of_book, vwap_fill_price, slippage_pp, shares_filled), identifying thin legs, and flagging forced directional risk. It also warns about the dominant loss mode in arb-bot P&L. 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 dense, with no wasted sentences. It is front-loaded with the purpose and structured into single-market and basket sections. A minor deduction because a wall of text could be better organized with bullet points or headers, but the content justifies its length.

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

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

With no output schema, the description fully enumerates return values for both modes (top_of_book, vwap_fill_price, theoretical_sum vs realizable_sum, thin_legs, etc.). It also explains input requirements, defaults, and edge cases. For a tool this complex, it is remarkably 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?

Although schema coverage is 100%, the description adds critical semantic distinctions: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode. It also clarifies the side parameter's auto behavior in basket mode. This goes well beyond the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges and positioning itself as a pre-trade risk check.

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 usage guidance is provided: '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, partial fills create unhedged directional risk), making the when-to-use unmistakable.

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 though annotations already declare readOnlyHint and idempotentHint, the description adds substantial behavioral detail beyond those safety hints. It discloses internal matching logic: skipped_cross_type/cross_subtype counters, temporal_alignment flags, and the two compatibility_warning scenarios. It also explicitly states that aligned:false makes spreads mathematically meaningless, which is valuable operational transparency.

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

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

The description is long but well-organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and uses all-caps for key terms to guide reading. Every sentence adds necessary nuance for a complex comparison tool, and the core purpose is front-loaded in the first sentence. It could benefit from tighter bullet formatting, but it earns its length.

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

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

With no output schema, the description thoroughly documents the response structure: leg-by-leg raw probabilities, matched spread top_spreads_pp, temporal_alignment, and the two skip counters. It also explains edge cases (non-equivalent bet shapes, no token overlap, temporal misalignment) and interprets each warning condition. This makes the tool virtually self-describing for an agent.

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

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

Schema coverage is 100%, so all parameters already have useful descriptions. The description enhances this by formalizing the 'two modes' concept, explaining that topic auto-fetches matching events and that explicit kalshi_event_ticker/polymarket_event_slug override the mapped sides. This gives an agent better mental models for parameter combinations, although the override semantics were already present in the schema.

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

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

The description clearly states it provides the cross-venue spread between Kalshi and Polymarket for the same resolving question, with a specific verb 'cross-venue spread' and scope. It distinguishes itself from siblings like polymarket_arbitrage by explicitly comparing two different venues rather than a single venue. Both core modes (topic shortcuts and explicit tickers/slugs) are enumerated, 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?

The description gives concrete when-to-use context: topic mode for pre-mapped macros, explicit mode for custom pairings, and explains that the spread is a real signal only when bet shapes are equivalent. It warns that most pre-mapped topics return compatibility_warning and that pre-mapped ≠ tradeable, setting accurate expectations. However, it does not name alternative sibling tools for situations where this tool would be inappropriate, so it lacks 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 cover the safe read-only, non-destructive, idempotent nature. The description adds meaningful behavioral context beyond annotations: the ability to list all keys by omitting the key argument, and the identifier-based scoping. It doesn't mention potential edge cases like missing keys, but the core behavior is well disclosed.

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

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

Three sentences, front-loaded with the primary action. Every sentence contributes: the first explains the core function, the second gives a use-case rationale, and the third covers scoping and companion tools. No redundant or filler content.

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 one optional parameter, no output schema, and strong annotations, the description is complete. It covers retrieval, listing, scoping, use case, and complementary tools, giving the agent everything needed to correctly 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?

The schema already fully describes the key parameter with 100% coverage. The description adds value by explaining the 'omit the key to list all' behavior, and reinforces the purpose of the parameter. This goes beyond simply restating the schema, earning above baseline.

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

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

The description clearly states the tool's function with specific verbs: 'Retrieve a value previously saved via remember, or list all saved keys.' It also gives concrete examples of what can be stored (ticker, address, research notes) and explicitly differentiates from sibling tools remember and forget.

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

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

Provides explicit usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the complementary tools to pair with (remember, forget) and explains the scoping behavior, giving the agent clear guidance on when to invoke this tool.

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

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

Annotations declare readOnlyHint=true, but the description discloses that mark_read:true flags returned events as read and changes future call results, implying a state mutation. This contradicts the read-only annotation, warranting a score of 1 with annotation contradiction flagged.

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

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

Three sentences, front-loaded with the core purpose, and each sentence adds value: what it returns, how to filter, and the alternative feed. No fluff or redundancy.

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

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

The tool has 5 optional parameters and no output schema; the description covers return payload fields, filtering, mark_read behavior, and alternative access. It omits unread_only and limit details, but schema descriptions fill that gap, making it nearly complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the mark_read side effect ('next call only shows newer ones') and mentioning citation_uri, enriching parameter understanding beyond the schema.

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

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

The description clearly states the tool pulls fired events from the subscription feed, with specific references to the evaluator-persisted feed and returned fields like citation_uri. It distinguishes itself from sibling tools like 'events' by emphasizing the subscription-feed and read-state semantics.

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

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

Provides clear context (polling, filtering, mark_read) and even suggests an alternative HTTP endpoint for scripts/dashboards. Does not explicitly exclude other tools or state when-not-to-use, but the specific feed context is sufficient.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds multi-source fan-out, fallback logic (GDELT preferred, GNews on rate-limit/5xx), USPTO soft-fail due to API sunset, and return structure with changes[] and citation URIs.

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?

Dense but efficient: every clause provides distinct value—trigger phrases, source list, fallback rules, parameter formats, output shape, or alternative tool. No filler, and the structure front-loads the core purpose.

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

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

Given the tool's complexity and lack of an output schema, the description covers all essential aspects: input formats, source behavior, fallbacks, return structure, and the distinguishing alternative. Nothing important is omitted.

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

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

Schema already documents all 3 parameters, and the description adds useful semantics for `since` (ISO vs relative shorthand, recommended '30d'/'1m') and clarifies `value` accepts ticker or CIK, reinforcing the schema descriptions without redundancy.

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 defines the tool as a change feed for a company over a time window, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly contrasts it with entity_profile, distinguishing it from a sibling tool.

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 natural-language trigger examples, explicit fallback behavior, and directly states when to use entity_profile instead. Also recommends typical 'since' values ('30d' or '1m'), giving concrete usage 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 state idempotentHint=true and destructiveHint=false, but the description adds valuable context: key-value storage scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. This details lifecycle and scoping beyond what annotations convey. 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?

Five sentences, each earning its place: purpose, usage examples, storage scoping, expiration behavior, and companion tools. Front-loaded with the primary purpose. No redundant or filler content.

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 memory tool with 100% schema coverage and no output schema, the description fully covers purpose, usage, persistence, scoping, and lifecycle. It is sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with clear definitions for key (with examples) and value (any text). The description mentions key-value pairing and gives real-world key examples in the usage section, but doesn't add significant semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with 'Save data the agent will need to reuse later', clearly identifying the verb (save) and resource (data for later reuse). It distinguishes itself from sibling tools by explicitly pairing with 'recall to retrieve later, forget to delete', and gives concrete use cases (ticker, address, preference).

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

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

It provides explicit 'Use when' guidance with concrete examples (resolved ticker, target address, user preference) and states complementary tools (recall, forget). It doesn't explicitly say when not to use, but the context is sufficient for an agent to select it appropriately.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description reveals valuable behaviors: graceful degradation if GLEIF/OpenFIGI is unavailable, explicit reporting of unresolved identifiers under `unresolved`, and cascading multi-endpoint lookups. These details help the agent anticipate edge cases and response characteristics.

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 purpose and usage, followed by a structured breakdown of supported types and their identifiers. It is longer than average but each sentence contributes necessary detail (two entity types, ownership data, degradation behavior). No filler or redundancy, though the opening list of example questions slightly delays the main statement.

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 compensates by specifying the identifiers returned (CIK, ticker, LEI, FIGI, RxCUI) and the `unresolved` field. It does not fully outline the JSON response structure, but it provides enough for an agent to know what to expect. The note about citations for drugs adds completeness.

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

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

Schema coverage is 100%: both `type` and `value` have descriptions, including examples (AAPL, 0000320193, ozempic). The description reiterates accepted input formats but adds no new parameter-level semantics; it focuses instead on output identifiers and enrichment behavior. This matches the baseline for full schema coverage.

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

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

The description opens with concrete example queries ('What's the ticker for…', 'find the CIK for…') and states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' The verb 'resolve' and resource (entity name to identifiers) are specific, and the line 'Use FIRST whenever you have a name but need an ID' clearly differentiates it from sibling tools.

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

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

Explicit guidance is provided: 'Use FIRST whenever you have a name but need an ID.' The description also illustrates when it applies via example queries and notes that it replaces 2-3 manual lookups. However, it does not mention any exclusions or alternative tools by name, so it falls slightly 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 state readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, establishing this as a safe, non-mutating read operation. The description adds value beyond this by revealing that the tool internally calls ai_visibility_check for each entity, ranks the results, and returns specific fields (score, confidence, signal density). This explains the tool's behavior without contradicting 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 three sentences, all informative. It front-loads the core purpose, then explains the mechanism and output, and ends with a concrete use case. Every sentence earns its place, and 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?

For a multi-entity comparison tool with no output schema, the description provides good context: it links to the sibling tool ai_visibility_check, describes the ranking and return fields, and gives a realistic scenario. It does not cover potential edge cases like entity resolution failures or what happens if an entity is not recognized, but the high schema coverage and clear annotations reduce the need for exhaustive behavioral detail.

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

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

The input schema already covers 100% of parameters with descriptions, including the optional models and _apiKey. The description adds meaningful semantics beyond the schema by clarifying that the first entry in entities is treated as the 'subject' for narrative and the rest are competitors. This helps the agent understand how to order the entities array, which is not fully specified in the schema.

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

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

The description uses the specific verb 'Compare' with a clear resource ('AI visibility across multiple entities side-by-side'), and distinguishes itself from sibling tools like ai_visibility_check by explicitly mentioning it probes multiple entities and ranks them. It also states the output (ranked list with score, confidence, signal density), making its purpose unmistakable.

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

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

The description gives a clear context ('competitive AI-marketing audits') and a user-facing question ('does Claude know about us as well as our competitors?'), indicating when to use the tool. It also implicitly contrasts with single-entity checks by mentioning it probes 'each entity with ai_visibility_check,' but it does not explicitly state when not to use it or name alternative tools for single-entity cases.

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

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

Beyond the readOnly/idempotent annotations, the description discloses latency (bundlephobia first measurement can take 5-30s) and partial failure behavior (sources_failed lists timed-out sources, rest still returns). It also notes ecosystem limitation. This adds substantial context over annotations.

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

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

The description is well-structured: front-loaded with the core purpose, then usage, return details, limitations, and failure mode. Every sentence adds substantive information without redundancy. Dense but efficient for a composite tool.

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 enumerates return fields, mentions failure modes, and specifies ecosystem scope. It covers the important operational details (latency, partial failures) making it complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no extra parameter details beyond what the schema provides; it does mention the default latest version and npm-only, but those are already in the schema descriptions. No additional semantic value.

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

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

The description clearly states the tool's purpose as a composite npm package evaluation check, fanning out to deps.dev and bundlephobia. It uses specific terms like 'should I add this npm package' and lists the data sources, distinguishing it from sibling tools like scan_competitor_ai_presence.

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

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

Explicitly states when to use: whenever an agent asks about safety, popularity, or size of an npm package. Also provides an alternative: for non-npm ecosystems, use deps.dev directly. This gives clear when/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?

Beyond the readOnly/idempotent annotations, the description discloses concrete behavior: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flagged, and every passage carrying an offset for verbatim verification. These detail the operation's mechanics and edge cases without contradicting annotations.

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

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

The description is dense but every sentence earns its place: definition, use case, integration, and technical details. It is front-loaded with the core action, and no fluff or repetition exists.

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 fills the gap by explaining return content (passages, offsets, similarity scores). It also covers the input cap, truncation behavior, and a usage workflow, making it fully complete for a moderately complex tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the purpose of 'text' (fetched record), 'query' (natural-language), and 'limit' (top-N), but does not add format or syntax details beyond the schema. It primarily restates what schema already documents.

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: 'Semantic search INSIDE a fetched record,' clearly distinguishing it from fetch tools. It also provides concrete examples (SEC 10-K body, article) and explicitly pairs with ask_pipeworx_grounded, making its unique role unmistakable.

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

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

The description gives an explicit when-to-use instruction: 'Use when the record is too big to cram into the prompt.' It also outlines a workflow with ask_pipeworx_grounded ('fetch with the gateway, ground over the relevant passages instead of the whole document'), which is a clear alternative and integration path.

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, the description adds significant behavioral detail: the account requirement for persistence, phone verification for SMS, the 10/day SMS cap, and the mechanics of the persistent feed. It also clarifies that subscription creation returns a new subscription id, which is useful operational knowledge not present in the annotations.

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

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

The description is dense but well-structured, front-loading the purpose and then systematically covering supported types and delivery channels. It is somewhat long and overlaps with schema content, but every sentence contributes useful context, and there is no filler.

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

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

The description omits the webhook delivery channel and the patent_grant and clinical_trial subscription types that are present in the schema. While the schema compensates for these gaps, the tool description is not fully complete on its own for a complex nested-object tool without an output schema.

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

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

The schema already provides 100% parameter coverage, but the description adds semantic value by giving concrete examples and explaining meaning (e.g., items:['5.02'] = officer change for sec_8k). This goes beyond the schema's basic property descriptions, though it does not fully compensate for the two omitted subscription types.

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 phrase, 'Create a proactive monitoring subscription to a live-data event stream,' which clearly states the action and resource. It also distinguishes the tool from siblings like list_subscriptions and unsubscribe by focusing on creation of a subscription and its delivery mechanics.

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 usage context, including the OAuth account requirement, the always-on feed, and how to consume alerts via recent_alerts or the registry URL. It does not explicitly name alternatives or exclusion conditions beyond the auth restriction, but the proactive-monitoring framing and feed-consumption hints give enough direction for an agent.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond annotations: it returns live catalog data, organizes results by category, and can be focused via topic. It does not contradict annotations.

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

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

The description is longer than average but packs in user-friendly query examples, category names, and usage instructions. It front-loads the entry-point phrasing and every sentence contributes value, though a tighter structure could improve scannability.

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

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

For a tool with no output schema, the description sufficiently explains the return content (category-bucketed examples with tool+arg shape) and how to invoke it. It also references sibling meta-tools, making it contextually complete for an onboarding scenario.

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

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

Schema coverage is 100% with a clear description for the optional topic parameter. The description adds examples ('finance', 'pharma', 'betting') and clarifies that omitting the parameter returns a cross-category spread, enriching the schema semantics.

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

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

The description clearly states this is the onboarding entry point for learning what to ask Pipeworx, returning category-bucketed example questions with the exact tool and argument shape. It uses specific verbs ('suggest', 'returns') and distinguishes from siblings like discover_tools by positioning itself as the FIRST tool to use when unfamiliar with the platform.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call it with no arguments or with a topic parameter. It also mentions learning how to call meta-tools, giving clear context for when this is appropriate 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 already declare destructiveHint=false and idempotentHint=true, but the description adds meaningful behavioral context: the row is deactivated rather than deleted, and this preserves historical events. This goes beyond the annotations' safety profile and clarifies the exact side effect, which is valuable for an agent.

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 no filler. The action is front-loaded, and each sentence provides distinct, useful information: what it does, ownership constraint, and non-destructive behavior. It is well-structured for quick parsing.

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

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

For a simple tool with one parameter and no output schema, the description covers the core operation, ownership restrictions, and the important consequence (deactivation, not deletion, with history preserved). It doesn't detail error states or response format, but given the simplicity and annotation support, it 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% for the single 'id' parameter, so the schema already documents its meaning. The description adds only minor extra context by mentioning 'by id' and ownership enforcement, which doesn't significantly enhance parameter understanding. 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 starts with 'Cancel a subscription by id,' which is a specific verb+resource that clearly states the tool's function. It also differentiates from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation, and the ownership constraint adds further clarity.

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

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

The description conveys usage context by stating ownership is enforced (only cancel your own subscriptions) and that historical events remain accessible via recent_alerts after cancellation. While it doesn't explicitly say when to use this over alternatives, the context is sufficient for an agent to infer appropriate usage.

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

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

The description adds significant behavioral context beyond the readOnly/idempotent annotations: it details the return values, the meaning of each verdict, and especially warns that 'could_not_verify' means the check did not happen and must not be treated as evidence. This is critical operational transparency not available from annotations alone.

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

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

Despite being lengthy, the description is efficiently structured: it opens with natural-language triggers, clearly separates the financial vs. general paths, enumerates output statuses, and ends with a warning about a critical edge case. Every section earns its place and no filler is present.

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

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

For a complex tool with two pipelines, multiple verdict statuses, and special warnings, the description covers purpose, usage, routing, output, and error semantics. It substantially compensates for the lack of an output schema by explaining what callers receive and how to interpret results.

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

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

While schema already documents both parameters with examples, the description adds nuanced meaning for tolerance_pct: it explains how to override the default for hallucination detection (set 1–2) and that the default is capped at 5. This goes beyond the raw schema description, justifying a score above baseline.

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

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

The description clearly identifies the tool as natural-language claim verification with specific verb phrases like 'fact check' and 'verify the claim that...'. It distinguishes from sibling tools by focusing on verifying user statements and mentions replacing multiple sequential calls, making it specific to claim verification rather than general search or research.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing behavior for financial vs. other claims, giving clear context and practical guidance without needing exclusions.

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