Catalogueoflife

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 model is free, passing _apiKey incurs direct charges from Anthropic, and the return structure includes score, confidence, signals, and raw_response. 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 compact—three sentences—and front-loads the core function (probe LLMs and score visibility) before addressing model defaults, return format, and use cases. Every sentence adds distinct value with 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?

Given the tool's moderate complexity (4 parameters, 1 required, no output schema), the description provides a complete picture: it specifies default and optional models, return structure (per-model score/confidence/signals/raw_response plus combined view), and typical use cases. The annotations cover safety aspects, so no further behavioral explanation is needed.

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

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

The input schema covers 100% of parameters with descriptions, so baseline is 3. The description adds high-level context (e.g., default model is Workers AI Llama-3.3-70b, _apiKey only needed if 'anthropic' is in models) but does not introduce meaning absent from the schema descriptions. It meets the baseline without exceeding it.

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

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

The description states a specific verb ('Probe') and resource ('one or more LLMs') and clarifies the output (visibility score 0-100 per model). It clearly distinguishes from sibling tools like ask_pipeworx, which provide conversational answers, and scan_competitor_ai_presence, which focuses on competitor scanning.

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to pass _apiKey (to also probe Anthropic) and the default model. However, it does not explicitly exclude any scenarios or name alternative sibling tools, so it misses the top score.

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

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

Annotations already declare readOnly/openWorld/idempotent and non-destructive, so the safety profile is covered. The description adds valuable behavioral context that this is a router ('Routes the question to the right one of 5,462 tools... fills arguments, returns the structured answer with stable pipeworx:// citation URIs') and notes it 'works on every tier, one fast call.' It could add more caveats about answer variability, but the disclosure is strong for an entry-point tool.

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 and front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH'). Every segment earns its place: use cases, examples, default status, escalation paths, and edge-case handling. It could be tightened slightly, but the richness justifies the 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?

Despite having no output schema, the description clearly states the return value ('structured answer with stable pipeworx:// citation URIs') and context around tool scope, source count, and example phrasings. It fully equips an agent to decide when to call this tool and what to expect from it, making it complete for a high-level default 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?

Input schema covers all 6 parameters with 100% coverage, including aliases and a clear description of the 'question' field. The description supplies examples but no additional parameter-specific semantics beyond what the schema already states; baseline 3 is appropriate because the schema does the heavy lifting.

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 'PREFER OVER WEB SEARCH for questions about current or historical data' and enumerates a wide range of domains, clearly asserting the tool's role as a general factual-answer router. It explicitly differentiates from siblings by naming ask_pipeworx_grounded and deep_research as step-up alternatives, so the purpose is specific and unambiguous.

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

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

The description gives explicit when-to-use guidance ('Use whenever the user asks...'), positions the tool as the default entry point ('START HERE'), and provides clear escalation rules ('Step up only when needed') with named alternatives for specific needs. It even handles the breaking-news edge case, leaving no ambiguity about when to select this tool over web search or siblings.

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

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

The description goes well beyond the annotations by disclosing that this is an experimental edge with candidate routing improvements enabled live, that no candidate is currently active, and that results are compared against the stable router to decide merges. It also clarifies it is a full working router with no fallback, providing important behavioral context not captured 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 four dense sentences, each earning its place: identity, current status, usage instruction, and clarification. It is front-loaded with the core definition and contains no filler or repetition.

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

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

The description covers tool scope, current behavior, and usage context, which is substantial for a router tool. It references the stable ask_pipeworx for response shape, so lacking an explicit response format description is acceptable. Overall, it is nearly 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?

The schema provides 100% coverage of parameters with descriptions of the question parameter and its five aliases. The description only says 'same arguments' and adds no parameter-level detail beyond the schema, so 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 identifies this as the beta version of ask_pipeworx, a universal router that handles the same 5,462 tools with identical arguments and response shape. It distinguishes itself from the stable ask_pipeworx sibling by its experimental routing improvements, so it is specific and differentiated.

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

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

It explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that it currently matches ask_pipeworx exactly and that results are compared against the stable router, implying ask_pipeworx is the stable alternative. This provides clear usage context and an implicit exclusion (when you don't want experimental routing).

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

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

Annotations cover read-only/idempotent safety, but the description adds key behavioral traits: refusal reasons (not_in_source, no_tool_match, etc.), the extra LLM call cost, and the strict evidence-based extraction process.

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 adds value—purpose, routing, response format, use cases, and cost trade-off. It is well-structured and front-loaded with the key differentiator.

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

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

Given no output schema, the description fully documents the success and refusal return shapes, plus usage context, making it self-sufficient for an agent to understand behavior.

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

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

All 6 parameters are aliases for the question with 100% schema coverage, so the description doesn't need to add parameter semantics; it does not, and the schema already explains them.

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

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

The description clearly identifies this as a hallucination-resistant answer mode that extracts answers only from tool results, and distinguishes it from the sibling ask_pipeworx by the extra LLM call and grounded extraction.

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 (high-stakes reads, quotations/citations) and when not (casual lookups prefer ask_pipeworx), providing clear alternative 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 goes well beyond the read-only/idempotent annotations by detailing behavioral nuances: fan-out to category-specific data packs, resolver contract with confidence levels and suggestions, handling of closed/dead markets, wide-spread illiquidity warnings, news fallback mechanisms, and the blocking nature of low-confidence matches. It also discloses the cancellation/refund rule parsing, which is critical for bet sizing. This is exceptional transparency 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 lengthy but extremely dense with necessary information for a complex tool. It is structured with clear section labels (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, etc.) which aids skimming. While some redundancy exists (e.g., repeated emphasis on low_confidence_match), every sentence serves a purpose: giving the agent actionable details about response handling and edge cases. It is front-loaded with the core use case and input format before diving into specifics.

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

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

Given that the tool has no output schema, the description compensates by thoroughly explaining all return shapes: result.market fields, result.analysis with model probability and edge warnings, result.evidence keys, result.market_match_confidence with alternatives and suggestions, parent_event for partition bets, news fallback fields, and special statuses (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread). It also covers the cancellation-rule semantics and safety checks. This is a complete picture for an agent to invoke and interpret the tool.

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

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

The schema already covers 100% of the parameters with clear descriptions (e.g., 'market' explains slug/URL/question; 'depth' explains quick vs thorough; 'include_raw' explains size and use case). The description augments this by providing concrete examples of fan-out for different bet categories (BTC, Fed, Hormuz, Yankees, etc.) and elaborates on response shape implications (e.g., result.analysis, result.market_match_confidence). It does not repeat the schema verbatim, adding value for parameter interpretation without being redundant.

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 ('Research') and clearly defines the resource ('a Polymarket bet') and the mechanism ('pulling the relevant Pipeworx data... in one call'). It also specifies the accepted input forms (slug, URL, question text) and the core output (evidence packet + market-vs-model comparison), which fully distinguishes it from sibling tools like polymarket_edges or arbitrage that target narrower functions.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context for invocation. However, it does not explicitly mention when NOT to use it or name alternative tools (e.g., for simple price checks, maybe a direct query tool would suffice), so it stops short of the full when/when-not/alternatives requirement.

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 key behavioral context beyond the readOnlyHint annotation by clarifying that only immediate children are returned ('immediate child taxa' and 'walk down one rank at a time'), which prevents mistaken expectations of recursive results. It also specifies the Catalogue of Life data source. No contradiction with annotations, which already indicate a safe, read-only, idempotent operation.

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: it opens with example queries that immediately convey the tool's function, then gives a precise definition. Both sentences earn their place with no filler, and the structure helps an agent quickly grasp the tool's 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?

For a simple read-only tool with an output schema and rich annotations, the description covers the essential aspects: what it does, when to use it, and the key behavioral nuance (immediate children). It does not mention error handling or edge cases, but these are less critical given the simplicity and availability of the 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 only documents 'limit' (1-1000, default 100), leaving 'id' and 'dataset' unexplained. The description implies 'id' is a taxon identifier via context ('parent taxon' and examples), but it does not explicitly describe the 'dataset' parameter or its possible values. This is a moderate gap given the low schema description coverage, though the purpose of the tool makes 'id' fairly obvious.

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

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

Description clearly states the tool lists immediate child taxa under a Catalogue of Life parent taxon, using specific verb+resource+scope. It also provides example queries and distinguishes itself as the tool for walking down the taxonomic tree one rank at a time, making it distinct from siblings like taxon, classification, or synonyms.

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 to walk down the tree of life one rank at a time,' which gives clear usage context. It does not explicitly mention alternatives or when not to use it, but the examples and definition make the intended use obvious, and sibling tool names provide implicit contrasts.

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 context beyond this by specifying the exact output structure (kingdom → phylum → class → order → family → genus → species) and clarifying that the input is a Catalogue of Life taxon ID, which sets expectations for the accepted identifier.

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: it opens with example natural language queries, then states the output and usage note. It is slightly verbose with the example list, but every part serves to help the agent match user intent and understand the tool's role in the workflow.

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

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

For a relatively simple read-only lookup tool, the description covers purpose, usage workflow, and the required parameter. The presence of an output schema means the return values need not be fully described, and the description even provides the output lineage chain. The only notable gap is the unexplained optional `dataset` parameter.

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

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

The schema has 0% description coverage, so the description must compensate. It explains the required `id` parameter as a Catalogue of Life taxon ID, but the optional `dataset` parameter is left completely unexplained. The example in the schema shows a sample value but no semantics, so the description only partially covers the 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 tool returns the full classification chain for a Catalogue of Life taxon ID, using a specific verb and resource. It also includes example queries that make the purpose unmistakable and distinguishes it from the sibling `search` tool by indicating it operates on the output of search.

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

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

The description explicitly says 'Use after `search` to get the lineage of a specific species,' which provides clear workflow guidance and names the alternative tool (search). This gives the agent a concrete condition for when to select this tool.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive, which lowers the bar. The description adds substantial detail beyond annotations: it explains the data sources (SEC EDGAR/XBRL, FAERS), how off-calendar fiscal years are handled, sorting behavior, and the return format with citation URIs. No contradiction with annotations.

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

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

The description is dense and front-loaded with trigger phrases, and every sentence carries useful information. It is longer than minimal but not wasteful; the length is justified by rich detail. A slight reduction because it could be more compact while retaining the same information.

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

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

Given the moderate complexity (2 params, no output schema), the description covers all necessary context: entity types, value formats, data sources, fiscal year handling, sorting, and return format. It fully informs the agent about what to expect from the tool, making it complete for this tool's scope.

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 tool description adds extra meaning by explaining what data each type retrieves (10-K revenue for company, FAERS counts for drug) and how results are sorted, going beyond the schema's field descriptions. This warrants an above-baseline score.

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

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

The description explicitly states that this tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with a specific verb and resource. It distinguishes itself from siblings like entity_profile by focusing on comparisons and listing concrete trigger phrases like 'X vs Y'.

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 guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides trigger phrase examples. However, it does not explicitly name alternative tools or state when not to use it, so it falls just short of an explicit alternatives-based score.

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 provide readOnlyHint, idempotentHint, and destructiveHint, but the description adds extensive behavioral context: account requirement, parallel decomposition, gaps[] for unanswered facets, never invented answers, resolvable citations, semantic excerpting of large records, contradictions detection, and latency expectations. This far exceeds the baseline and adds substantial value.

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

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

Although the description is long, every sentence provides essential operational detail, and it is logically structured (account → definition → use cases → depth semantics → citation behavior → latency). It is dense but not wasteful; could arguably be tightened, but the content justifies the 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 explains the findings packet structure (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps, contradictions, hop field). It also covers account requirements, latency, and the differences between depth levels. For a complex tool with two params and no return schema, this description is exceptionally 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 covers both parameters fully, but the description enriches them by explaining depth levels ('quick=3, standard=5, thorough=8'), which is not fully captured in the schema, and the paid requirement for thorough. It also reinforces that 'question' can be broad and multi-part. The additions meaningfully go beyond the structured schema.

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

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

The description clearly states the tool performs 'grounded multi-source research' across Pipeworx's structured data sources in one call, using specific verbs and resources. It explicitly differentiates from open-web search and names sibling alternatives, making it impossible to confuse with other tools.

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

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

The description gives explicit usage guidance: best for broad/multi-part questions, use ask_pipeworx for single lookups or breaking/current news, and requires an account with paid options for thorough depth. It provides clear when-to-use and when-not-to-use scenarios, and even names the exact alternative tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds concrete behavioral details: it returns top-N results with names, descriptions, and full input schemas, and each result is ready to call directly without a second schema lookup. This goes beyond the annotations and clarifies the output format and operational property.

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

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

The description is concise and front-loaded: it states the core purpose in one sentence, then the usage context, and finally the return format and recommendation to call first. Each sentence serves a distinct purpose, and the domain list, while long, is valuable for helping the agent understand the tool's scope. No unnecessary fluff.

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

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

This is a simple discovery tool with a query+limit schema and no output schema, yet the description fully explains what it does, when to use it, what it returns (names, descriptions, full schemas with examples), and that results are directly callable. The operational detail about not needing a second schema lookup completes the picture for an agent deciding whether and how to invoke it.

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

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

The input schema has 100% description coverage, documenting the query parameter and its aliases (q, task, search, description) as well as limit with defaults and max. The description reinforces that query takes a natural language description of a data/task and mentions 'top-N' which maps to limit, but it adds no new semantic meaning beyond what the schema already provides.

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

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

The description opens with 'Find tools by describing the data or task,' clearly specifying the verb (find) and resource (tools). It distinguishes itself from the many domain-specific sibling tools by positioning itself as the discovery/meta tool, with a broad scope spanning many data categories.

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

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

It explicitly states 'Use when you need to browse, search, look up, or discover what tools exist for' and lists a wide range of domains. It also adds 'Call this FIRST when you have many tools available,' providing a clear when-to-use context, though it does not explicitly mention when not to use or name specific alternatives, so it stops short of a 5.

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

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

Annotations declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond that: it fans out across multiple sources in parallel, patents soft-fail due to the USPTO API sunset, and news uses a GDELT→GNews fallback. This goes beyond simple operation safety.

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 efficiently packs essential details for a high-complexity tool. It front-loads with user intents, then systematically enumerates return fields and data sources. Each sentence adds value, though it could be tightened slightly without losing information.

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

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

Given no output schema, the description compensates by itemizing all return fields and data sources. It covers input constraints, fallback behavior, and limitations. It lacks explicit error/rate-limit details, but for a read-only tool with this level of complexity, the description is adequately complete.

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

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

Schema coverage is 100%, with both parameters ('type' and 'value') already well-described. The description adds examples ("AAPL", "0000320193") and repeats the name-not-supported caveat, but doesn't introduce meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a 'full cross-source profile of a US public company' and provides concrete user intents (e.g., 'Tell me about X'), making its purpose unmistakable. It differentiates from sibling tools by explicitly saying names are not supported and to use resolve_entity first.

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

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

Explicitly states to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' providing clear when-to-use guidance. It also specifies when not to use it (names not supported) and directs users to resolve_entity as 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds context about what is deleted ('previously stored memory') and why ('clear sensitive data'), which goes beyond the annotations. It does not contradict annotations; idempotentHint=true is consistent with deletion.

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 concise sentences. The first sentence front-loads the purpose, and the second provides actionable usage context. No superfluous words or repetition of schema 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?

For a simple one-parameter destructive tool, the description, combined with annotations and schema, is complete: it covers purpose, usage scenarios, pairing with siblings, and the resource affected. No output schema is needed for a delete operation, and the description does not leave significant gaps.

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

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

The input schema has 100% coverage for the single 'key' parameter, so the baseline is 3. The description does not add additional parameter-level detail beyond what the schema already explains, but it does give semantic context ('previously stored memory by key') that lightly reinforces the parameter's meaning.

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 action ('Delete a previously stored memory by key') and the resource it operates on (memories). It distinguishes itself from sibling tools 'remember' (store) and 'recall' (retrieve) by explicitly pairing with them, making the purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also names complementary tools ('Pair with remember and recall'), offering clear alternatives and context.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description explains the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output format as 'a single text blob ready to drop at site-root/llms.txt.'

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

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

Three sentences cover purpose, process, and use cases without any fluff. The main action is front-loaded, and every sentence adds value.

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

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

For a simple read-only tool with complete annotations and schema, the description is sufficient. It states the output format, making it complete even without an output schema. Minor gaps like edge cases are not essential here.

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 both url and max_links fully described in the schema. The description does not add parameter-specific details, so it does not exceed the baseline for complete 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 a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It clearly distinguishes this from sibling tools like scan_competitor_ai_presence by focusing on generating the file rather than analyzing or scanning.

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

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

Provides concrete use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It gives clear context for when to use, though it doesn't explicitly name alternatives or 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?

With readOnlyHint, openWorldHint, and idempotentHint already in annotations, the description adds meaningful behavioral context: it lists the exact return fields, restricts to the caller's own subscriptions, and implies that only active subscriptions are returned by default. This goes beyond the annotations and fully discloses the tool's scope and output shape.

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, no filler. The first sentence states functionality and return values; the second gives actionable guidance. Information is front-loaded and every clause 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?

There is no output schema, so the description's enumeration of return fields (id, type, params, created_at, last_fired_at, fire_count) is essential and complete. The single optional parameter is explained via the 'active' phrase and the usage note covers the main use cases. Given the tool's simplicity, nothing significant is missing.

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

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

The schema already describes include_inactive at 100% coverage, so the baseline is 3. The description adds value by using 'active subscriptions' to imply the default filtering and by noting that the returned id is useful for canceling, which gives practical meaning to the parameter. This lifts it slightly above baseline.

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

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

The description opens with 'List the caller's active subscriptions,' which clearly states the verb (List), resource (subscriptions), and scope (caller's active). This distinguishes it from sibling tools like subscribe and unsubscribe, and the added detail about returning specific fields reinforces its read-only purpose.

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

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

The description explicitly says to use it 'to review what you're monitoring before adding more or to find an id to cancel,' which provides clear context for when to invoke the tool. It does not explicitly name alternatives like subscribe/unsubscribe, but the reference to 'adding more' and 'canceling' implies them, so it is strong but not fully aligned with sibling names.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds a concrete result contract ('0 or 1 hit plus close alternatives') and exact-match behavior, which go beyond the annotations and help set expectations. No contradiction exists.

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

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

Two tightly packed sentences with front-loaded example queries; no filler or redundant restatement of the tool name. Every sentence adds value.

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

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

For a simple lookup tool with an output schema and read/idempotent annotations, the description covers purpose, disambiguation, and return cardinality. The only material gap is the undocumented dataset parameter, but overall the agent has enough to select and invoke the tool correctly.

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

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

Schema coverage is only 33%, so the description must compensate. It meaningfully clarifies scientific_name (exact Latin binomial) and authorship (disambiguation with homonyms), but the optional dataset parameter is never explained. This leaves a notable gap for a low-coverage 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?

Description opens with concrete query formulations ('Is [Panthera leo] a valid scientific name') and states a specific function: exact scientific-name match returning 0 or 1 hit plus close alternatives. This clearly distinguishes it from broader siblings like search or taxon by emphasizing exact matching and homonym disambiguation.

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 when you have a precise Latin name and want to confirm acceptance or distinguish homonyms.' It also explains when to pass authorship to disambiguate. No explicit alternatives are named, but the use case is clearly bounded.

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

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

Annotations are all false/neutral, so the description carries the full behavioral burden. It fully discloses the claim_token flow (filing without an account returns a token, which can be reused later to read resolution status), rate limiting (5 per identifier per day), cost (free, no quota impact), and the team's daily digest cadence. It also warns against pasting the end-user's prompt, adding behavioral context beyond what annotations convey. 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?

Although the description is long, every sentence delivers critical information: purpose, usage triggers, exclusions, claim_token mechanics, rate limits, and cost. It is front-loaded with the core purpose, and each clause earns its place. The density is high with no filler, making it an efficient and well-structured description for an AI agent.

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 absence of an output schema and the moderate complexity of 4 optional params (including a nested object), the description fully covers what an agent needs to know: when to file, what to include, how to check resolution, rate limits, cost, and the exclusion case. It also implies the immediate response (claim_token when no account) and the follow-up pattern. There are no significant gaps that would leave an agent guessing.

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 per-parameter descriptions, so the baseline is 3. The description adds value by explaining how the claim_token is used later in a follow-up call, and by instructing users to describe issues in terms of Pipeworx tools rather than pasting prompts—context not present in the schema. However, the type enum and context object meanings are already well documented in the schema, so the description's marginal contribution is limited. Score 4 reflects solid augmentation without being revolutionary.

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 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly states the verb (tell/feedback) and resource (Pipeworx team). It explicitly enumerates the feedback types (bug, feature/data_gap, praise) and immediately distinguishes this tool from the sibling data-query tools by restricting use to tools served by this Pipeworx connection. This is a specific, non-tautological purpose statement.

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

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

The description provides explicit 'Use when' conditions for each feedback type (bug, feature/data_gap, praise), and an explicit exclusion: if the tool came from a different MCP server, file it there instead. It also gives guidance for uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists') and clarifies the intended scope. This goes well beyond any minimal 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 mark the tool read-only and idempotent; the description adds meaningful behavioral details: data source ('derived from CF analytics-engine'), privacy ('no PII'), output shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h'). This enriches the agent's understanding well beyond the structured hints.

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

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

The description is compact and front-loaded, with the core function in the first sentence. The use-case list, data-source note, and caching note each add distinct value with no fillers, making every sentence purposeful.

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

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

For a read-only tool with one optional parameter and no output schema, the description fully covers what the agent needs: what is returned (top tools, packs, counts), the window options, and caching. The annotations further assure safety, making the tool self-contained for invocation.

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

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

The sole parameter (window) has 100% schema description coverage, including nuance about short vs. long windows. The tool description merely references the windows ('24h, 7d, or 30d') without adding new semantics, matching 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 opens with a precise statement of what the tool reports ('What other AI agents are calling on Pipeworx right now') and lists concrete outputs ('top tools, top packs, and total call volume'). It also includes three specific use cases that make its purpose unmistakable and distinguish it from sibling tools like discover_tools.

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

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

The 'Useful for' section provides three actionable scenarios: discovering hot data sources, confirming a canonical tool, and aligning with agent needs. This is strong guidance, though it does not explicitly name alternatives or say when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral depth without contradiction. It discloses the fill check logic (realizable_edge_pp ≤ 0 means don't trade), semantic anchor Jaccard threshold, placeholder partition filter, and output structure. These are valuable non-obvious behaviors beyond annotations.

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

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

The description is long but every sentence carries actionable detail. It is structured in labeled blocks (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and opens with the core purpose. No fluff or repetition; the density is justified by the tool's complexity.

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

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

Given no output schema, the description compensates by outlining the response structure (opportunities[], partition_check fields). It covers all modes, parameter semantics, edge cases (placeholders, similarity threshold, fill book depth), and cross-references a related tool. The description is self-sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% and includes descriptive comments for both parameters. The description enriches this by explaining what the tool does with each parameter (walks child markets, flattens markets, runs comparator), providing concrete example slugs/questions, and adding mode-specific behavior. This goes beyond the schema's basic type/description.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by naming the specific detection mechanisms and referencing the fill-risk tool for custom sizing. The purpose is unambiguous and well-differentiated.

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

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

Explicit guidance is given for when to use no args, `event`, or `topic`, including a recommendation ('event (recommended for a specific market)'). It explains what each mode does and even notes that cross-event mode catches patterns single-event misses. The description also points to polymarket_fill_risk for custom sizing, providing a clear alternative and boundary.

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

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

Even with annotations declaring read-only, idempotent, and non-destructive behavior, the description goes far beyond by disclosing caching (Cached 1h at the KV level), model-specific filtering (placeholder-slug drops, partition overround with per-sport alpha), rare-by-design gates, and response structure (segments, fed_candidates/fed_note, _diagnostics). It also warns about edge erosion ('your edge may already be in the price') and explains why fed candidates are excluded from ranking. This is rich behavioral context.

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

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

The description is long and dense, but it is front-loaded with the core purpose and organized into clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). Every sentence adds useful information for a complex tool, though it could be trimmed for brevity without losing core value. It is not rambling 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?

With no output schema, the description fully compensates by detailing the response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics) and the fields carried by every opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers edge cases like stale markets and federation caveats, making it complete enough for an agent to confidently invoke the 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?

Although schema coverage is 100%, the description adds critical parameter semantics. It explains the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) and clarifies subtleties like min_kelly not applying to partition arbs because parent-level kelly_fraction_half is always 0. It also provides context for slippage_pp ('Polymarket has zero trading fees... bid/ask + thin depth typically eats 20-50bp'). This meaningfully exceeds the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states what the tool does and distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker by emphasizing the Pipeworx disagreement and the multi-segment output (model_driven, structural_arbitrage, concentrated_longshot).

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 when-to-use context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It implies the tool is for opportunity discovery with filtering knobs, but it does not explicitly name alternative tools or state when not to use it. Since there are siblings like polymarket_arbitrage, explicit exclusion would push it to 5, but the clear use case earns a 4.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds substantial context: 60-day snapshot TTL, cache-miss-based snapshot creation, daily-close decay calculation, and the meaning of gaps in snapshot_dates. This goes well 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 detailed but efficiently structured: purpose, parameters, response format, and limitations are each covered. Every sentence adds value, with no filler. The response section is particularly well organized for a complex 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?

No output schema exists, so the description takes full responsibility for explaining return values—tracked, expired, snapshot_dates—along with their field semantics and interpretation. It also covers limitations like TTL and data gaps, making the tool complete for selection and invocation.

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

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

The input schema already provides full descriptions for both parameters (100% coverage). The description adds minimal new meaning—it restates lookback and snapshot family concepts already present in the schema. Baseline 3 applies since schema does the heavy lifting.

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: 'Edge persistence and decay telemetry' built from daily snapshots, and answers a specific question about edge age and shrinkage. It distinguishes itself from the sibling 'polymarket_edges' tool by focusing on historical persistence 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 implies when to use the tool by contrasting fresh vs. old edges and explaining how a 3-week-old wide edge is a different trade. It provides clear context for assessing edge persistence, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds valuable behavioral context: mode selection, default side/size behavior, clamping of size_usd, ladder walking, verdict outputs, and the risk of partial basket fills leaving unhedged positions. This significantly exceeds what annotations provide, with 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?

Though long, the description is tightly structured into single-market and basket sections, with each sentence carrying essential information. No redundancy; the length is justified by the tool's two modes and the need to convey precise semantics and risks.

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?

No output schema exists, so the description compensates by enumerating all return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers edge cases like thin books and partial fills, making it fully self-sufficient 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 covers all 4 parameters, and the description enriches each: market vs event exclusivity, side defaults per mode, size_usd dual interpretation (spend vs target proceeds vs settlement notional), and clamping range. This goes beyond the schema descriptions, giving the agent full semantic understanding.

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 the tool as a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' with a clear verb+resource. It explicitly distinguishes single-market and basket modes and positions itself as a pre-trade validation step for arbitrage signals, setting it apart from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial basket fills convert to directional risk) and states prerequisites (requires market or event), making the intended context 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?

Annotations declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context beyond these: it details safety fields, compatibility warnings, temporal alignment, and skipped_cross_type semantics. It openly states limitations ('pre-mapped ≠ tradeable') and explains edge cases. No contradiction; instead, it enriches the safety profile.

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

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

The description is lengthy but tightly structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS). Every section earns its place by covering a distinct aspect: modes, output, and safety/limitations. No filler; the detail is necessary for such a complex 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?

Given the tool's complexity (3 optional params, no output schema), the description is extremely thorough. It explains response structure, spread calculation, temporal alignment, and compatibility warnings. The explicit caution about pre-mapped shortcuts being untradeable is a valuable completeness touch. Nothing critical is missing.

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

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

Schema coverage is 100% with good descriptions, but the description adds meaningful semantics about parameter interaction: it explains that 'topic' provides pre-mapped shortcuts and that explicit tickers override the mapped side. This clarifies the relationship between parameters beyond the schema, which is valuable for selecting the correct combination.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from siblings (e.g., polymarket_arbitrage) by focusing on cross-venue comparison, and details two modes of operation, making the purpose unambiguous.

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

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

The description provides clear contextual guidance on when to use the tool, explaining the two modes (topic shortcuts vs explicit tickers) and when spreads are meaningful ('when the bet shapes are equivalent') vs not ('when they aren't the tool says so'). It also warns that pre-mapped topics often return compatibility_warning, setting expectations. However, it doesn't explicitly name alternative tools for when this isn't the right choice, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds meaningful context beyond that: scoping to identifier types, the ability to list all keys, and the pairing with remember/forget. No contradiction.

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

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

Three sentences, all informative; no filler. Front-loaded with the primary action, then examples, then scoping and relationships.

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

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

For a simple single-parameter tool with strong annotations, the description covers purpose, usage, scoping, and related tools. It doesn't specify edge-case returns (e.g., missing key), but that's not essential given the simplicity.

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 documents the key parameter (100% coverage). The description adds illustrative examples of what keys might contain and the behavior of omitting the key, reinforcing but not substantially extending 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 specific verbs ('Retrieve', 'list') and clearly identifies the resource ('a value previously saved via remember'). It also explains the optional behavior of listing all keys, which distinguishes it from simple retrieval 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 states clear usage context: 'Use to look up context the agent stored earlier' with concrete examples. It also references sibling tools (remember, forget) but does not explicitly exclude any alternative, so no full when-not guidance.

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

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

The description discloses a significant side effect: setting mark_read:true flags events as read and affects future calls. This directly contradicts the annotations, which set readOnlyHint=true, implying no state changes. The contradiction is serious and misleading for an agent assessing safety. Other disclosed details (payload fields, polling) are useful, but the contradiction forces a score of 1.

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

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

The description is concise and well-structured: four sentences with clear progression (purpose → payload → filters → mark_read behavior → alternative endpoint). Each sentence adds value, and no effort is wasted on repetition or fluff.

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

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

Given 5 parameters and no output schema, the description is quite complete: it explains the return payload fields (source, citation_uri, raw event), filtering options, the mark_read side effect, and polling suitability. It lacks explicit error behavior or edge cases, but covers the essential usage details for a read-oriented polling tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains the effect of mark_read ('so the next call only shows newer ones') and gives a concrete example for type ('sec_8k'). This enhances understanding of parameter behavior, though it does not elaborate on limit, since, or unread_only beyond the schema.

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

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

The description clearly states the tool's core function: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed), the action (pull/returns most recent alerts), and includes distinguishing details like evaluator-written events and payload fields. This effectively differentiates it from sibling tools like list_subscriptions (which lists subscriptions) or recent_changes (which tracks changes).

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

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

The description gives clear context on when to use the tool: for polling alerts, filtering by type and since, and marking events as read. It also mentions an alternative direct HTTP endpoint for scripts/dashboards, implying the tool is for interactive use. However, it does not explicitly contrast with sibling tools or state when not to use it, so it falls short of a 5.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses the fan-out architecture, GDELT-to-GNews fallback on rate limits or 5xx, USPTO PatentsView API sunset causing soft-failure, and the exact return shape (changes[] grouped by source, total_changes count, citation URIs). This is rich behavioral context that annotations alone do not provide.

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

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

The description is dense but well-structured: it opens with query paraphrase examples, then defines scope, data sources, fallback behavior, date syntax, return format, and sibling distinction. Every sentence carries useful information; no filler or redundancy.

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

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

With no output schema, the description compensates by specifying the return structure (changes[] grouped by source, total_changes, citation URIs). It also covers entity type restriction, source limitations, and the recommended `since` defaults, making it fully sufficient for an agent to select and invoke the tool correctly.

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

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

The schema already documents all three parameters at 100% coverage, including the `since` formats and `value` ticker/CIK behavior. The description largely restates the `since` syntax and adds no new parameter-level detail, so the baseline score of 3 applies.

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

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

The description clearly states this is a 'change feed for a company in the last N days/weeks/months' and enumerates the sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes itself from the sibling entity_profile by explicitly directing users who want a static profile to that 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 explicit guidance on when to use this tool with natural language examples, and explicitly says to use entity_profile instead when a static profile is wanted. Also clarifies fallback behavior between GDELT and GNews, which helps the agent decide under rate-limiting conditions.

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

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

Discloses key persistence details beyond the annotations: key-value storage scoped by identifier, 24-hour retention for anonymous sessions, and persistence for authenticated users. No contradictions with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

Every sentence contributes value: purpose, usage scenario, storage model, security semantics, and sibling tool pairing. Information is front-loaded and the length is proportionate to the tool's scope.

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

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

Given the simple two-parameter tool with full annotations and no output schema, the description covers all essential aspects: what it saves, how it persists, who can access, and how to interoperate with related tools. No critical information is missing.

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

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

Schema coverage is 100% with both 'key' and 'value' documented. The description echoes these examples but adds no new parameter-level meaning beyond what the schema already provides. It appropriately relies on the schema, so baseline 3 is warranted.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later' and clearly distinguishes storing (remember) from retrieving (recall) and deleting (forget), which are 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?

Provides explicit when-to-use guidance ('Use when you discover something worth carrying forward... so you don't have to look it up again') and names companion tools for follow-up actions ('Pair with recall to retrieve later, forget to delete').

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds meaningful behavioral detail: it cascades through multiple lookup endpoints internally, returns citation URIs, and supports auto-disambiguation. This goes well beyond the annotations and fully discloses the tool's runtime behavior and outputs.

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

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

The description is moderately long but well-structured: starting with user-phrase examples, then a clear purpose statement, then usage guidance, and then a detailed breakdown of supported types. Every sentence contributes value, though a slightly tighter version could reduce redundancy (e.g., repeating 'returns' for each type).

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?

In the absence of an output schema, the description adequately explains return values for each entity type (including citation URIs) and input formats. It does not mention error cases or rate limits, but for a read-only resolver with these annotations, the provided details are sufficient for most use cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter understanding by giving concrete examples (ticker 'AAPL', CIK '0000320193', names) and specifying that the tool auto-disambiguates and accepts both brand and generic drug names. This adds practical meaning beyond the schema's field descriptions.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides specific examples ('What's the ticker for…') and lists supported entity types (company, drug), distinguishing it from siblings by explicitly positioning it as the first step when a name needs an ID.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also implies this replaces manual lookups, but it does not explicitly name alternatives or provide when-not-to-use conditions. Despite minor gaps, the context is clear enough for an agent to select this tool 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?

The description adds behavioral context beyond annotations by stating it 'Probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and describes return metrics. Annotations already mark it readOnly/idempotent, so the process-level detail is valuable.

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 plus a brief example. It front-loads the main purpose and then efficiently covers behavior, use case, and return format with no redundant words.

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

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

Covers purpose, usage, internal process, and return value (ranked list with score, confidence, signal density). The lack of output schema is compensated with explicit return details. Good annotations reduce the need for more behavioral caveats.

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

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

The input schema already provides full descriptions for all 4 parameters (100% coverage). The description reinforces the 'entities' parameter as 'your brand + N competitors' but does not add new syntax or format details beyond the schema.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies a distinct verb-resource pairing and differentiates from siblings like ai_visibility_check (single-entity) and compare_entities (generic) by emphasizing multi-entity AI visibility comparison with ranking.

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

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

Provides a clear use case: 'Useful for competitive AI-marketing audits' with a concrete example question. It implies when to use this tool (for multi-entity comparison) but does not explicitly exclude alternatives or mention 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 annotation (readOnlyHint: true, idempotentHint: true), the description adds critical behavioral context: bundlephobia's first measurement can take 5–30s, partial failures degrade gracefully, and 'sources_failed' will list timed-out sources. This gives the agent a clear model of latency and failure behavior without contradicting any annotation.

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 main purpose and uses a compact, information-dense structure. Each sentence serves a purpose: overview, usage triggers, return summary, ecosystem scope, and failure behavior. Despite its length, it remains readable and free of fluff.

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

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

Since there is no output schema, the description compensates by detailing the returned summary fields, per-advisory details, links, alternative versions, and failure reporting. It also clarifies the vertical scope (NPM-only in v1) and the fallback path for other ecosystems, making it 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?

The schema describes both parameters thoroughly (package name with scoped support, version default behavior), so the description adds little new meaning. It reasserts the NPM-only constraint but does not go beyond the schema. With 100% schema coverage, 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 a clear, specific statement of the tool's purpose: a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It names concrete data sources and metrics, and it is easily distinguishable from all sibling tools, none of which relate to dependency scanning.

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

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

The description explicitly states when to use the tool ('Use whenever an agent asks...') and provides guidance for alternatives outside the NPM ecosystem, pointing users to 'deps.dev:version directly'. It also covers graceful degradation when bundlephobia is slow, giving the agent actionable expectations.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive behavior. The description adds valuable behavioral context: data source (Catalogue of Life, ~2.1M species), what entities are covered, the meaning of `status` values, and that results include taxon IDs for follow-up calls. 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 dense but well-structured: it opens with representative query patterns, states the authority and source, lists return fields, and ends with a filter tip. Every sentence contributes value, though the length is slightly above minimal due to the example enumeration.

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 an output schema present, return values are already documented, yet the description still clarifies the kind of results (name-usages with scientific name, authorship, rank, status, taxon ID). It covers the tool's scope, source reliability, filtering guidance, and follow-up tools, making it adequately complete for the tool's complexity.

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

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

Schema description coverage is 83%, above the 80% threshold, so the schema carries most parameter meaning. The description adds usage nuance for `rank` ('filter by rank when narrowing') and echoes the query examples, but it does not meaningfully explain `offset` or `dataset` beyond the schema. No significant gap requiring compensation.

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

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

The description clearly states the tool performs authoritative taxonomic lookup for species/genus/family/higher taxa, with specific example queries. It distinguishes itself from siblings by explicitly mentioning follow-up calls to `taxon` or `classification`, and its scope (Catalogue of Life checklist) differentiates it from `synonyms`, `vernacular`, and `name_match`.

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

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

The description provides clear context for when to use the tool (taxonomic lookups, common name to scientific name, verifying species existence) and how to narrow results using the `rank` filter. It names `taxon` and `classification` as follow-up tools, but it does not explicitly state when not to use this tool in favor of those alternatives or other siblings like `synonyms` or `vernacular`.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds valuable behavioral context beyond annotations: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. 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, tightly written, front-loaded with the primary purpose, and every clause adds value—no redundant filler. It packages a lot of information efficiently.

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 explains return values (passages, offsets, scores) and the truncation flag. It lacks exact output field names/structure, but given the tool's moderate complexity and existing parameter descriptions, 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 description coverage is 100%, so baseline is 3. The description adds usage context (e.g., 'text you already pulled') but does not introduce new parameter semantics beyond what the schema already covers; it supports the workflow without altering parameter understanding.

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

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

The description states a specific verb ('Semantic search') and resource ('inside a fetched record'), and clearly distinguishes from siblings by emphasizing 'INSIDE' a record and pairing with ask_pipeworx_grounded. It also specifies the output (top-N passages with offsets and scores).

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

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

Explicitly states when to use: when the record is too big to fit in the prompt, and describes the workflow with ask_pipeworx_grounded as an alternative. This provides clear context and points to a sibling tool, fulfilling the when/alternatives guideline.

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 contradicts the annotations: it says 'Returns the new subscription id' implying each call creates a new subscription, while idempotentHint=true indicates repeated calls with the same parameters have the same effect. This is a direct contradiction, and per the rubric, this dimension must be scored 1 and flagged as an annotation contradiction.

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

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

The description is information-dense and well-structured, starting with the core purpose, then supported types, then delivery channels. It uses a compact long sentence but every clause adds detail. It earns its length given the tool's complexity, though it could be slightly more scannable.

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

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

Despite the idempotency contradiction, the description is remarkably complete for a tool with nested objects and no output schema. It covers all subscription types, delivery options, authentication requirements, rate limits, webhook verification details, and the return value (subscription id). It even mentions the feed retrieval path as an alternative.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value by providing concrete examples for each type (e.g., items:[\"5.02\"], topic:\"fed\", sponsor/condition) and clarifying constraints like 'sponsor or condition required', which goes beyond the schema's generic 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: 'Create a proactive monitoring subscription to a live-data event stream.' The verb 'create' and resource 'subscription to a live-data event stream' are explicit, and it distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description explains when to use this tool for proactive monitoring, and it contrasts with pulling via recent_alerts or the registry endpoint. It also provides prerequisites (OAuth account) and the distinction that anonymous/BYO cannot persist subscriptions. However, it does not explicitly state 'do not use for one-time queries' or name alternatives for non-persistent use.

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

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

The description discloses what the tool returns (category-bucketed example questions), how those examples are structured (each with the exact tool and argument shape), and that they are drawn from a live catalog of thousands of tools. It also describes the no-argument vs. topic behavior. Annotations already cover the read-only, idempotent, non-destructive nature, and the description adds behavioral detail 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 front-loaded with natural-language query examples and organized into purpose, output, and usage sections. It is a bit verbose with multiple example phrasings, but each example helps with phrase matching and the structure makes it easy to scan. No wasted sentences.

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 zero required parameters and no output schema, the description is fully complete. It covers when to use it, what it returns, how to vary the call, and its relationship to meta-tools. There are no important gaps for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents the topic parameter with allowed values and the instruction to omit it for a cross-category spread. The description repeats example values and says 'to focus', but adds no meaningful new semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool as the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape needed to answer them. It is distinguished from sibling tools like ask_pipeworx and discover_tools by its focus on suggesting what to ask and teaching how to call meta-tools. The opening query examples reinforce the purpose in plain language.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', which gives a clear usage trigger. It also explains when to omit vs. pass the topic parameter. However, it does not explicitly name a sibling tool to use once the user already knows what to ask, so it lacks a clear when-not-to-use 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows it is a safe read operation. The description adds domain context that synonyms are mapped to a single accepted taxon and that these are historical/alternative names, which goes beyond the annotations' binary safety flags.

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

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

The description is a single, dense sentence with embedded query examples, a clear definition, and a usage statement. It is front-loaded with the tool's purpose and contains no wasted words.

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

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

The tool has only two parameters and an output schema, so return values are covered externally. The description gives strong usage context and domain details, but the total absence of parameter semantics (what 'id' refers to, what 'dataset' does) leaves an important gap for a tool with 0% schema description coverage.

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 0%, and the description does not mention either parameter ('id' or 'dataset'). The schema example '7XCCF' provides no semantic explanation. With no parameter documentation in the description and an ambiguous 'dataset' field, the agent has no information beyond the bare property names.

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 'list synonyms (alternative or historical scientific names)' with a specific scope ('currently mapped to a single Catalogue of Life accepted taxon'). It also embeds natural language query examples, distinguishing it from siblings like 'classification' or 'vernacular' by focusing on synonym/historical name mapping.

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 includes explicit usage guidance: 'Use to map outdated taxonomy to current names.' It also frames example queries, giving the agent clear context for when to invoke this tool. However, it does not name alternative tools or explicitly state when not to use it, so it stops short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful context by specifying the returned data (accepted concept with name, rank, authorship) and suggesting how to combine with related tools. No contradictions. It does not cover potential edge cases like missing IDs, but the annotations reduce the burden.

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

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

The description is a single, well-structured sentence that front-loads the tool's action and resource, then efficiently guides usage with related tools. No redundant information 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?

The description covers the core function, return fields, and related operations, which is adequate given the output schema and annotations. However, the optional 'dataset' parameter is left undocumented, and the description does not cover potential edge cases or error behavior, leaving a small gap for a 2-parameter 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 0%, so the description must compensate. It clearly explains the 'id' parameter as the COL taxon ID, but does not mention the 'dataset' parameter at all. Thus it only partially compensates for the lack of schema descriptions.

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

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

The description clearly states the tool fetches a single accepted taxon record by COL taxon ID, with a specific verb (Fetch) and resource (Catalogue of Life accepted taxon record). It also distinguishes from siblings by explicitly naming classification, children, and vernacular as alternatives for related lookups.

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

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

The description explicitly tells the agent when to use this tool versus alternatives: 'Pair with classification for lineage, children to descend the tree, or vernacular for common names.' This provides clear when-to-use and 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?

Discloses ownership enforcement (only your own subscriptions) and that rows are deactivated rather than deleted, providing context beyond the annotations. The annotations (readOnlyHint=false, destructiveHint=false) are consistent, and the description adds useful detail about the operation's side effects.

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 with no filler, front-loaded with the core action, and each sentence contributes essential information about behavior or consequences. The structure is clean and highly scannable.

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

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

For a simple one-parameter tool, the description covers the action, constraint (ownership), and side effect (deactivation) comprehensively. No output schema exists, but the return value is not essential for this operation, and the description gives enough context for correct invocation.

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

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

The single parameter 'id' is fully described in the schema ('Subscription id (uuid) returned by subscribe') with 100% coverage. The description adds little beyond 'by id', so the schema carries the burden; a baseline of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource. It is unambiguously distinguished from siblings like subscribe and list_subscriptions by its function, and the name itself reinforces the purpose.

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

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

The description implies this tool is used to cancel subscriptions created via subscribe, and mentions recent_alerts as where historical events remain visible. However, it does not explicitly state when not to use it or name alternative tools, though the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read-only operation. The description adds modest behavioral context by noting the tool returns specific fields (taxon name, authorship, rank, status, source dataset) and that it is a single-record fetch, but it does not describe any hidden behaviors such as rate limits or error handling. With annotations covering the safety profile, the description's additional contribution is limited, making 3 appropriate.

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 that is front-loaded with the core verb and resource, then adds the return fields and usage context. It packs all essential information without redundancy or filler words. Every phrase earns its place, making it 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 the essential aspects of the tool: what it does, how to invoke it (by COL ID), what it returns, and its place in the workflow (after search/name_match). An output schema exists, so return values are further specified there. No additional context like pagination or authentication is needed for a single-record read-only fetch. The description is complete for the tool's complexity.

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

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

Schema description coverage is 0%, so the description must compensate for missing parameter details. It does so by clarifying that 'id' is the COL ID and implicitly tying 'dataset' to the 'source dataset' in the return fields. This gives the agent enough meaning to understand the role of both parameters, though it could be more explicit about the format of 'id' or optionality of 'dataset'. Given the low coverage, this is solid compensation, but not perfect, so a 4 is warranted.

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 ('Fetch') and resource ('single Catalogue of Life name-usage record') and identifies the key lookup mechanism ('by its COL ID'). It also distinguishes from sibling tools like 'search' and 'name_match' by emphasizing it retrieves the full structured record after those preliminary steps.

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

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

The description explicitly states when to use the tool: 'Use after search or name_match to retrieve the full structured record.' It provides clear context for the typical workflow, but does not explicitly mention when not to use it or list alternative tools beyond the implicit pipeline. This is strong guidance but lacks explicit exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds meaningful behavior: the exact percent-delta math for company-financial claims, automatic fall-through to a grounded pipeline, verbatim evidence, pipeworx:// citations, and the five possible verdicts. It also discloses the routing logic and the tolerance cap, which goes beyond the structured 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 reasonably concise for the tool's complexity, front-loading the intended use with trigger phrases and concluding with a compact summary of outputs and efficiency gains. Every sentence carries meaningful information, though it is long enough that a slight tightening could help; it earns a 4.

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

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

For a two-parameter, no-output-schema tool, the description fully covers what the tool does, how it routes, what verdicts it returns, what evidence format it provides, and when the tolerance parameter matters. The annotation set is rich, and the description complements it without redundancy.

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 semantics by explaining how tolerance_pct interacts with the claim wording ('Overrides the tolerance implied by the claim wording') and why it matters for hallucination detection ('set 1–2 for hallucination detection'). The claim parameter gets illustrative examples directly in the schema, and the description's examples reinforce the expected format.

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 explicit natural-language triggers and a precise verb phrase ('natural-language claim verification against authoritative sources'). It clearly distinguishes itself from sibling research tools by focusing on verify/validate claims with verdicts, and describes the two-part pipeline (SEC EDGAR/XBRL fast path vs. grounded pipeline).

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

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

It explicitly states when to use it ('whenever the agent needs to check whether something a user said is factually correct'), distinguishes the company-financial path from any other factual claim, and notes it replaces multiple sequential calls. This provides clear context versus sibling tools like deep_research, compare_entities, or bet_research.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds context about multilingual name lists and the Catalogue of Life source, but does not disclose error behavior or limitations. 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 concise and front-loaded with example queries, conveying the tool's purpose and usage in one sentence. It avoids unnecessary repetition and structure is clean.

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

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

Given the simple nature of the tool, the presence of an output schema, and strong annotations, the description is reasonably complete. It explains the purpose, gives examples, and identifies the data source. The main gap is parameter documentation, but that falls under parameter semantics.

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 0%, and the description does not explain the 'id' or 'dataset' parameters. Although it mentions 'Catalogue of Life taxon', it doesn't explicitly connect this to the required id parameter or provide format guidance, leaving parameter meaning largely unexplained.

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 specifies the action ('list') and resource ('common/vernacular names for a Catalogue of Life taxon'), with concrete examples such as mapping 'Panthera leo' to 'lion'/'leon'/'lwów'. This clearly distinguishes it from related scientific-name tools like synonyms.

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 includes an explicit use case ('Use to map...') and provides natural language query examples. However, it does not explicitly state when not to use this tool or directly compare it to alternatives like synonyms, leaving some room for ambiguity.

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