Pangaea

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

Beyond the readOnly/idempotent annotations, the description adds significant behavioral context: the default free model (Workers AI Llama-3.3-70b), the requirement for a BYO Anthropic API key, and the cost implication ('you pay Anthropic directly for those calls'). It also specifies the return structure, which is not covered by annotations.

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

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

The description is three dense sentences: it opens with the core action, then covers configuration and output, and ends with practical use cases. Every sentence earns its place without redundancy.

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

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

With no output schema available, the description compensates by specifying the per-model return shape ('{score, confidence, signals, raw_response}') and the combined view. It also clarifies the default model, API key requirement, and use cases, making the tool fully understandable 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?

The schema already provides 100% parameter coverage with descriptions. The description adds extra meaning by explaining the default model behavior and that `_apiKey` enables Anthropic probing, which goes beyond the schema's basic 'optional' flag. This justifies a score above the baseline of 3.

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

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

The description uses a specific verb ('Probe') and clearly identifies the resource ('one or more LLMs') with a concrete output ('score visibility (0-100) per model'). It is unmistakably clear what the tool does, but it does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence', which could overlap in purpose.

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

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

The description gives clear contexts for use ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), but it does not mention when not to use the tool or recommend alternative tools for specific scenarios. This is a clear usage context without exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds substantial behavioral context on top: it routes questions into 'one of 5,581 project across 1,463 sources', fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. This gives the agent a clear model of what happens when the tool is invoked.

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 purposefully structured, front-loading 'Prefer Over Web Search' first and then covering categories, trigger phrases, examples, and a clear directive to 'Start Here For Most Questions'. Some redundancy exists between the long source list and the broad 'anything requiring authoritative structured data' phrasing, but the sentence is still efficiently presented.

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

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

For a broad open-world factual tool with no output schema, the description provides enough to invoke it correctly: it states the input kind, the types of domains covered, provides explicit examples, and describes the return format as a structured answer with citation URIs. It does not describe fallback/error or no-match behavior, which would require more completeness for a 5.

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

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

Schema coverage is 100% and the schema already documents the question parameter and its aliases, so the description does not need to repeat those details. The description adds value by showing that the caller supplies only a natural-language question while the tool itself fills arguments, plus it provides examples of effective queries (e.g., 'Apple's latest 10-K', 'adverse events for ozempic').

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

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

The description clearly defines the tool as a natural-language router that answers factual questions from 5,581 tools over 1verified sources and returns structured answers with pipeworx:// citations. It distinguishes itself strongly from web search, but it does not explicitly differentiate from the closely named sibling tools ask_pipeworx_beta and ask_pipeworx_grounded, so it is not a full 5.

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 with trigger phrases ('what is', 'look up', 'find', 'get the latest', 'current') and says 'Prefer over web search' and 'Start here for most questions'. It also covers alternatives by saying this is preferred even when web search could answer; however, it lacks explicit exclusions or when-not-to-use guidance, especially relative to the Pipeworx variant 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?

Behavioral traits are richly disclosed beyond the readOnlyHint/openWorldHint/idempotentHint annotations. The description explains the tool's experimental nature, that routing changes are enabled live, and that results are compared against the stable router for merge decisions. It also preempts confusion by stating 'Falls back to nothing — this IS a full working router.'

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

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

The description is informative and front-loaded with the core identity ('Beta version of ask_pipeworx'). The date-specific detail about the last candidate retirement adds context but is slightly verbose; still, every sentence serves a purpose without redundancy.

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

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

The description is complete for a tool that takes a natural-language question, covering its experimental state and relationship to the stable router. It references 'same response shape' as ask_pipeworx, which is sufficient given no output schema, though a brief note on return format would have been helpful.

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, with each parameter described (question plus aliases). The description adds minimal parameter semantics, merely noting 'same arguments' as ask_pipeworx, which relies on knowledge of the sibling tool. This meets the baseline but doesn't elevate it.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, acting as an identical universal router with the same 5,581 tools and arguments. It explicitly differentiates from the stable sibling by mentioning 'candidate routing improvements enabled live,' making the purpose and distinction unambiguous.

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

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

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that when no candidate is active, the tool matches ask_pipeworx exactly, helping agents decide between the beta and stable versions. This is direct and actionable.

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 annotations already establish read-only, idempotent, non-destructive behavior, and the description adds crucial behavioral context: refusal with specific refusal_reason categories, evidence as a verbatim quote, and the guarantee that extraction relies solely on tool output. No contradiction with annotations exists.

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

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

The description is dense but every sentence earns its place: it states the mode's purpose, explains the underlying mechanism, specifies the return shape and refusal reasons, and gives practical usage and cost guidance. The most decision-relevant information is front-loaded.

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

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

With no output schema, the description fully compensates by detailing both the success payload and refusal payload, listing concrete refusal reasons, and explaining the cost tradeoff versus the sibling tool. An agent has enough context to invoke it correctly and interpret its results.

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

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

Schema coverage is 100% and the question parameter is already well-described in the schema, including alias names. The description adds no additional parameter-level semantics beyond what the schema provides, 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 a grounded, hallucination-resistant answer mode that extracts answers only from fetched tool results, and explicitly contrasts it with ask_pipeworx by highlighting the extractive behavior. This makes its purpose distinct from the sibling tools without ambiguity.

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

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

It gives explicit usage guidance: use when an answer will be quoted, cited, or acted on, and prefer ask_pipeworx for casual lookups due to the extra LLM call cost. This directly tells the agent when to choose this tool versus the 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses extensive behaviors: parallel fan-out, resolver contract, low-confidence short-circuit, closed-market handling, wide-spread flag, and cancellation-rule refund logic. It even cautions 'ALWAYS inspect these before trusting the analysis block', adding significant value beyond what annotations provide.

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

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

The description is well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and is front-loaded with a clear purpose. However, it is quite long and verbose; while every section adds useful context, the sheer length makes it less concise than ideal for quick parsing.

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

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

With no output schema, the description thoroughly documents all relevant return structures (result.market, result.analysis, result.evidence, result.parent_event, news fields), safety modes (low_confidence_match, market_closed_or_inactive), wide-spread tradeability, and cancellation-rule risk. It covers edge cases and provides actionable guidance, making it highly complete for a complex tool.

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

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

The schema has 100% coverage for all three parameters with good descriptions, so the baseline is 3. The description adds semantic value for the 'market' parameter by enumerating accepted input formats (slug, URL, question text) and explaining the resolver+classifier+fan-out consequence. However, it doesn't add much for 'depth' or 'include_raw' beyond the schema, so a modest bonus is justified.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the output (evidence packet + market-vs-model comparison) and distinguishes itself from sibling tools by focusing on bet-specific research with market resolution and classifier fan-out.

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

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

It explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides detailed fan-out examples for different bet types. However, it doesn't explicitly name alternative tools or when not to use it, so it lacks explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling (AAPL Sep, NVDA Jan), sort behavior ('sorted by primary metric'), and output composition ('paired data + pipeworx:// citation URIs per entity'). 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 front-loaded with trigger phrases and every sentence packs specific value: preference rule, per-type data sources, fiscal year handling, sorting, output format, and efficiency claim. Despite its length, there is no filler or repetition of schema content.

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

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

For a tool with no output schema, the description compensates fully: it covers what the tool does, when to use it, per-type data behavior, constraints (2–5 entities), output format (paired data + citation URIs), and sorting semantics. Complexity is moderate-high, and the description addresses all selection and invocation needs.

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

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

Schema coverage is 100% and both parameters are well described, so the baseline is 3. The description adds value by explaining the semantic payload of the type parameter ('type="company" pulls LATEST 10-K revenue + net income + cash + long-term debt...' and 'type="drug" pulls FAERS adverse-event counts...'), which goes beyond the schema's terse enum labels.

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

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

The description states a specific verb+resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call,' and goes beyond naming by detailing exactly what is pulled (10-K revenue/net income/cash/debt for companies; FAERS/FDA/trial counts for drugs). It distinguishes from siblings by explicitly saying it 'replaces 8–15 sequential lookups,' differentiating it from single-entity tools like entity_profile.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' naming the alternative and giving a clear when-to-use trigger. It also provides concrete query-phrase examples ('Compare X and Y', 'X vs Y', 'rank these companies') that help an agent recognize when this tool applies.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that it returns 'full metadata' for a single dataset, which hints at the scope of the response. It does not disclose error behavior or other edge cases, but this is acceptable given the simple lookup nature and presence of an output schema.

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

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

The description is a single, focused sentence that front-loads the core purpose. Every word is necessary, with no filler or repetition of structured data.

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

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

For a one-parameter lookup tool with complete schema coverage and an output schema, the description is fully sufficient. It states the input type, the resource, and the outcome. The annotations and output schema cover safety and return structure, so no further context 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 parameter schema already documents 'id' with a description and example (921708). The tool description repeats the same example without adding new meaning. Since schema coverage is 100%, the description provides no additional semantic value beyond what the schema already conveys.

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

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

The description explicitly states the tool returns full metadata for a PANGAEA dataset given a numeric ID, using a specific resource and parameter. It distinguishes itself from sibling tools like dataset_by_doi by specifying the numeric ID input.

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 phrase 'by its numeric ID' implies usage when a numeric ID is available, but it does not explicitly mention alternative tools (e.g., dataset_by_doi) or provide when-not-to-use guidance. Usage is implied rather than explicitly stated.

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 non-destructive behavior, covering the safety profile. The description adds useful context about accepting either a bare DOI or a doi.org URL, but does not disclose other behavioral traits like rate limits or error handling. With annotations present, this is adequate.

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, efficient sentence with no filler. It is front-loaded with the key action and resource, making it easy to parse quickly.

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

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

The tool is simple with one parameter, comprehensive annotations, and an output schema available. The description fully covers what an agent needs to know for invocation and expected results; no additional context is required.

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 the `doi` parameter with 100% coverage and an example. The description adds extra meaning by noting that a doi.org URL is also accepted, which is not stated in the schema. This enrichment justifies a score above the baseline.

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

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

The description clearly states the tool's function: retrieving full metadata for one PANGAEA dataset. It specifies the method (by DOI) and the scope (one dataset), distinguishing it from sibling tools like `dataset` or `search` that may operate differently.

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

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

The description clearly implies when to use the tool: when you have a specific PANGAEA DOI. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to select it over broader search tools.

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

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

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description still adds substantial value: authentication/paywall requirements, latency expectations (15-60s, thorough ~90s), the internal decomposition into parallel tool calls, the guaranteed evidence+citation structure, explicit gaps[] for unanswered facets with a 'never invented' honesty guarantee, and per-depth behavioral differences. The unambiguous 'NOT open-web search' disclaimer directly manages a common agent misconception about openWorldHint. No contradictions with 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?

Dense but every sentence earns its place — there is no filler. It front-loads the one-sentence core purpose and key caveat (not open-web) before the detail on internal mechanics and depth semantics. It is long, but the tool is genuinely complex (2 params with deep behavioral differences, 5 siblings, cross-tool guidance); a shorter version would sacrifice the usage rules that make it safe. Slight over-length from the nested 'thorough'-vs-'standard' iteration details that could arguably live in the schema enum.

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 2-param tool with no output schema and read-only/high-idempotency annotations, the description covers everything an agent needs to select and invoke correctly: scope boundaries (structured catalog vs. live news), the parallel-decomposition behavior, the guaranteed return payload shape (evidence + citation + fetched_at + gaps[]), depth tradeoffs, and a concrete question-shaped example. There is no missing context an agent would have to guess at.

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 both params fully with 100% coverage summary and enum meanings on depth. The description meaningfully extends this: it explains the question param's acceptable breadth ('broad/multi-part is fine — decomposition is the point'), and enriches depth semantics by naming the actual behaviors behind each enum value ('standard re-angles unanswered gaps', 'thorough chases the best leads + recovers gaps, 6-tool fan-out'). Solid added value on top of a complete schema.

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

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

The description opens with a sharp verb+resource statement: "Grounded multi-source deep research over Pipeworx's 1463 STRUCTURED data sources in ONE call," immediately distinguishing it from open-web search and from its closest sibling ask_pipeworx. It names the mechanism (decompose → route in parallel → evidence packet) and the return artifact (findings with citations and a gaps array). There is no ambiguity about what this tool does.

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

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

Explicit when-to-use and when-not-to-use: use for broad/multi-part structured-data questions ('compare X and Y's regulatory + financial exposure'), prefer ask_pipeworx for single lookups and for breaking/current news ('what's the world saying about X'), and it names the specific reason (news routes to live news tools; deep_research returns mostly empty gaps for non-catalog topics). Also flags the prerequisite (account, paid tier for depth:'thorough'). This is exemplary guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses meaningful behavior: results include full input schemas with curated examples and are 'ready to call directly, no second schema lookup needed.' This adds substantial context about the return format and eliminates ambiguity about the output experience.

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

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

The description is well-structured and front-loaded: purpose first, then usage, domain list, return behavior, and usage guidance. Every section contributes value, though the synonym cluster 'browse, search, look up, or discover' is slightly redundant and the domain list, while useful, adds length.

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

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

Given the absence of an output schema, the description compensates by explicitly explaining what is returned (names, descriptions, schemas with examples) and the top-N ranking behavior. Combined with full parameter coverage and safe annotations, the description is complete enough for initial use.

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

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

Schema description coverage is 100%, with all aliases (q, task, search, description) and the limit parameter fully described. The description adds no parameter-level meaning beyond what the schema already provides; it only reiterates the high-level 'describing the data or task' concept.

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 'Find tools by describing the data or task' and enumerates specific domains (SEC filings, FDA drugs, weather, etc.), distinguishing it from sibling tools that are data-retrieval focused. It also specifies the output (top-N tools with names, descriptions, and full schemas), making its purpose unmistakable.

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

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

Provides clear context: 'Use when you need to browse, search, look up, or discover what tools exist' and gives an ordering cue ('Call this FIRST...'). However, it does not explicitly name alternatives or say 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 mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond this: it fans out across multiple external APIs, mentions that the USPTO PatentsView API is sunsetting and will soft-fail, describes a GDELT→GNews fallback for news, and specifies output details like sorting of fundamentals by period_end DESC. 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 a clear summary, but it is quite lengthy and covers many details in paragraph form. Every sentence adds value—listing sources, outputs, and limitations—so it is not wasteful, but a more structured layout (e.g., bullet points) could have improved scannability.

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

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

Given complexity (multi-source fan-out, no output schema) and the absence of structured return specifications in annotations, the description thoroughly explains what the tool returns: cik, company_name, recent_filings with URIs, fundamentals fields, patents, news, and LEI. It also notes limitations (PatentsView sunset, name input unsupported) and fallback behavior, 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 input schema already documents both parameters thoroughly: type is restricted to 'company' and value explains ticker/CIK formats and the need to use resolve_entity for names. The description repeats this information with examples ('AAPL', '0000320193') but does not add new semantic meaning beyond the schema. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description explicitly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It lists concrete sources and output fields, and distinguishes itself from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and by directing name-only queries to resolve_entity.

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: use when the user asks for a holistic view ('Tell me about X', 'research Acme', 'brief me on Tesla'). It explicitly warns against using it for names ('names not supported') and directs to resolve_entity as an alternative. It also implies not to chain multiple lookups when this tool can do it in one call.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world behavior. The description adds useful context beyond annotations by explaining that results are top values with counts and that the aggregation can be scoped by a full-text query. 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 a single, front-loaded sentence that conveys the action, output shape, and optional scoping parameter, followed by illustrative examples. There is no filler or redundant content.

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

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

Given full schema coverage, a present output schema, and rich annotations, the description provides all essential information: what the tool returns, how to scope it, and examples of valid fields. No critical details are missing for selecting and invoking 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that 'field' is a category field with concrete examples and by explaining that 'query' is an optional full-text scope, which enriches the bare schema definitions.

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

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

The description opens with a specific verb and resource: 'Aggregate matching datasets by a facet', then defines the output as top values with counts and gives concrete field examples. This clearly distinguishes the tool from sibling search/list tools by focusing on faceted aggregation.

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

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

The description clearly implies this tool is for getting top category values with counts and notes that the full-text query is optional, providing context for when to use it. However, it does not explicitly name sibling alternatives or state when not to use this tool, so it lacks formal exclusion guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower. Description adds context about clearing sensitive saved data but doesn't disclose additional side effects like irreversibility or permissions, which would be useful.

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

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

Two concise sentences, front-loaded with the action, no filler. 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 one-parameter destructive tool with good annotations, the description fully specifies purpose, usage, and related tools. No output schema needed.

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

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

Schema covers the single 'key' parameter with 100% description, so baseline 3 applies. Description doesn't add syntax or format details beyond the schema, which is sufficient for a simple string key.

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

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

Description uses specific verb 'delete' with resource 'memory' and key mechanism, clearly differentiating from sibling tools like remember and recall. It states exact scope and operation.

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

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

Provides explicit use cases ('context is stale, task done, clear sensitive data') and recommends pairing with remember and recall, but lacks an explicit 'when not to use' clause.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds valuable behavioral context: it fetches the page, extracts metadata and links, and emits a single markdown blob. This goes beyond annotations without contradicting them.

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

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

Three sentences with no fluff: purpose, process, and use cases. Front-loaded with the core action and output, making it easy to scan. Every sentence earns its place.

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

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

The tool is simple with only two parameters, both documented, and annotations are strong. The description communicates the return format (single text blob) and use cases. It does not detail the exact llms.txt format, but that is a standard known to the agent. Sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'any URL' but does not elaborate on parameter details beyond what the schema already provides. No additional semantic value is added for max_links.

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 ('Generate') and resource ('llms.txt file') and clearly states the scope ('for any URL'). It explains the extraction and output process, making the tool's function unambiguous and distinct from sibling tools.

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

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

The description provides 'Useful for:' scenarios (client site indexing, own project drafting, competitor auditing), which clarify when to apply the tool. It does not explicitly mention alternatives or exclusions, but the listed use cases give sufficient contextual 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 and destructiveHint. The description adds substantive behavioral context: it lists the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifies the scope ('the caller's' and 'active' by default). This goes well beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the action, then return fields, then usage context. Every word earns its place with no redundancy or fluff.

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

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

Despite no output schema, the description explicitly lists all return fields, making the response shape clear. It also provides usage context and covers the tool's simple parameter set. This is complete for a list-style read tool.

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

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

The input schema covers 100% of the parameter details, including a description for include_inactive. The tool description does not add any extra parameter semantics, so 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 starts with a specific verb and resource: 'List the caller's active subscriptions.' It clearly identifies what the tool does and distinguishes it from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

The description gives explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool and implicitly contrasts it with subscribe (adding) and unsubscribe (canceling).

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

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

Annotations only say readOnlyHint=false, so the description adds meaningful behavioral context: 'Rate-limited to 5 per identifier per day,' 'Free; doesn't count against your tool-call quota,' and the claim_token workflow for later retrieval. It also states 'The team reads digests daily and signal directly affects roadmap,' giving the agent a realistic sense of consequences.

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

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

The description is dense but every sentence earns its place: purpose, usage triggers, MCP-server exclusion, token workflow, rate limit, and cost. It is front-loaded with the core action and uses capitalization and punctuation to keep the long paragraph navigable.

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 4-parameter tool with a nested context object and no output schema, the description covers usage scope, non-usage, token handling, rate limits, and business impact. It is complete enough for an agent to decide and invoke correctly without additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later') and by giving examples of what counts as bug/feature/data_gap, reinforcing the enum semantics beyond the schema.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools by framing it as feedback about Pipeworx itself, not a research or search operation.

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

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

It explicitly lists when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog... or when something worked surprisingly well (praise).' It also gives a clear exclusion and alternative: feedback about other MCP servers should be filed with that server, not here.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: data derived from 'CF analytics-engine,' states 'no PII,' and explains caching ('Cached 5min-1h depending on window'). This goes beyond annotations 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 moderately concise. The first two sentences state the core function, followed by a three-item use-case list and two sentences of data provenance/caching details. All content is relevant, though the 'Useful for' list could be trimmed without losing meaning.

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

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

For a simple one-parameter tool with no output schema, the description covers return content ('top tools, top packs, and total call volume'), the data shape ('(pack, tool, count)'), privacy ('no PII'), and caching behavior. It does not detail the exact response structure, but that's acceptable 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 covers the single optional 'window' parameter fully with enum values and explanatory text ('24h (default) | 7d | 30d'). The description repeats the window options in passing but adds no new parameter semantics, so the baseline 3 applies.

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

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

The description opens with 'What other AI agents are calling on Pipeworx right now' and explicitly states it returns 'top tools, top packs, and total call volume.' This clearly identifies the tool's purpose and distinguishes it from sibling Q&A tools like ask_pipeworx or discovery tool discover_tools.

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

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

The description includes a 'Useful for' list with three concrete scenarios: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. This gives clear guidance on when to invoke the tool, though it doesn't explicitly state when not to use it or name alternative tools, so score 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?

Despite annotations already indicating safe, read-only, open-world behavior, the description goes well beyond by disclosing crucial operational details: the fill check against live CLOB depth, the exact condition for non-tradeability ('realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it'), the partition filter logic, and the structure of the response. This level of behavioral detail is not present in annotations and is highly valuable for the agent to understand the tool's internal logic and pitfalls.

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 it is structured into clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and every sentence contributes substantive information. It is front-loaded with a one-sentence summary of the tool's purpose. However, the sheer length and density may be slightly overwhelming, so it earns a 4 rather than a 5 for conciseness.

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

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

With no output schema, the description fully documents the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}' in event mode. It also explains secondary outputs like 'skipped_low_similarity' and the fill check results, making the tool's behavior complete enough for an agent to invoke and interpret results correctly.

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

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

The input schema already has 100% coverage, but the description adds significant meaning beyond the schema: it explains the difference between 'event' and 'topic' modes with concrete examples ('fed-decision-may-2026' vs 'Strait of Hormuz traffic returns to normal'), elaborates on what each parameter triggers (walking child markets vs. cross-event scanning), and clarifies the recommended use case for each. This transforms the parameters from mere schema names into actionable concepts.

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 action: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly identifies the tool's function and methodology, distinguishing it from sibling tools like polymarket_edges or polymarket_fill_risk by mentioning the unique checks and the multi-mode behavior.

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

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

The description provides explicit usage guidance for each mode: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also gives a recommendation ('event (recommended for a specific market)') and references an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk'), clearly telling the agent when and how to use this tool versus alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description richly discloses behavior: caching ('Cached 1h at the KV level'), filtering logic (placeholder-slug filter, 20% placeholder skip), per-segment gating (concentrated_longshot 'rare-by-design'), and diagnostic output (_diagnostics funnel counters). It also warns about 24h moves and edge being already in price, which is significant 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 long but well-structured, with clear uppercase section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) that aid scanning. Every detail serves a purpose for a complex tool, but the density is high and could overwhelm an agent; it earns a 4 rather than 5 because some details (sport-specific α values) are exhaustive.

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 top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics), explaining what each segment contains, and noting diagnostics for empty segments. It covers return-field semantics (edge_pp_net, kelly_fraction, market.liquidity) and provides conditional warnings, making the tool's behavior fully comprehensible 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?

Although schema coverage is 100%, the description adds substantial semantics beyond field names. It explains the 'TRADEABLE-EDGE KNOBS' (min_liquidity, max_spread_pp) and their purpose (drop opportunities where edge isn't realizable), details slippage defaults with market reasoning (zero fees, bid/ask 20-50bp), and clarifies the special meaning of min_partition_leg_kelly for basket trades. This is valuable context the schema does not provide.

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 scanning Polymarket markets to surface opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and the resource 'Polymarket markets,' and differentiates from sibling tools by explaining it's built for 'what should I bet on today' discovery without paging hundreds of markets.

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

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

The description clearly states its use case (opportunity discovery) and even notes exclusions (Fed bets are surfaced but excluded from ranking due to unreliable signal). However, it does not explicitly name alternative sibling tools (e.g., polymarket_edge_tracker for tracking) or provide explicit when-not-to-use guidance, 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 readOnlyHint=true and idempotentHint=true, and the description fully reinforces this by describing read-only telemetry. It goes beyond annotations to disclose detailed behavioral traits: snapshots only written on cache-miss, gaps meaning no scan, decay computed on |edge_pp_net| with negative values signifying SELL YES, and the bounded history due to TTL. It also clarifies that decay uses daily closes of edge_pp_net, not intraday. This is rich, transparent disclosure.

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 highly structured with labeled sections (RESPONSE, LIMITS) and dense, informative sentences. It front-loads the core question and then systematically explains return fields and constraints. While more verbose than a simple two-sentence description, every sentence carries unique behavioral or contextual value, earning a high but not perfect score due to the sheer 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?

No output schema exists, so the description fully compensates by explaining the response structure (tracked[], expired[], snapshot_dates[]) with details on what each contains, including trend categories, decay_pp_per_day, lifespan_days, and median lifespan as a competition clock. It also covers edge cases like snapshot gaps and TTL limits. Given the tool's complexity, this description is remarkably complete.

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

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

The input schema already provides full descriptions for both parameters (days: default 14, clamp 2-30; window: 24hr | 1wk | 1mo, default 1wk). The description adds minimal extra value: it reiterates the default for days but says 'max 30' rather than 'clamp 2-30', and labels window as 'snapshot family' but does not alter the schema meanings. Since schema coverage is 100%, the baseline is 3, and the description does not meaningfully upgrade 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 clearly identifies the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes itself from the sibling polymarket_edges by focusing on persistence/decay rather than current edges. The verb+resource structure 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 provides clear context for when to use the tool: it contrasts fresh vs. old edges, implying use for evaluating whether an edge is decaying before acting. It also explains interpretation of expired[] and snapshot_dates[] for assessing competition, and explicitly notes limitations (60-day TTL, cache-miss writes). While it does not name a specific alternative tool as a replacement, it clearly implies this is the go-to for historical edge telemetry versus current edge snapshots.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral depth by explaining that it 'walks the ladder,' returns top-of-book, VWAP, slippage, shares_filled, and a verdict. It also surfaces risk-critical behavior: partial basket fills can convert an arb into an unhedged directional position, which is the dominant loss mode. No contradiction with annotations.

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

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

The description is long but well-structured: it starts with a concise one-line summary, then separates REQUIRES, SINGLE-MARKET, BASKET, and usage guidance into clear sections. Each sentence adds necessary detail for a complex two-mode tool. The final warning, while useful, could be trimmed slightly, but overall it is appropriately sized for the tool's complexity.

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

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

With no output schema, the description fully enumerates the return values for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). It also covers edge cases like thin books and partial fills. The tool is complex, and the description leaves no practical 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?

Even though schema coverage is 100%, the description significantly enriches parameter understanding. It explains that `market` is for single-market mode and `event` for basket mode, clarifies `side` options and defaults in both contexts, and reinterprets `size_usd` as 'max spend on buys, target proceeds on sells' in single-market and 'settlement notional S (shares per leg)' in basket mode. This goes far beyond 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 and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings by stating exactly when to use it (before acting on polymarket_arbitrage or polymarket_edges signals) and by naming the two modes (single-market and basket). This leaves no ambiguity about the tool's unique role.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also clarifies the distinction between single-market and basket modes, and explains the default/modes for each parameter. This goes beyond generic context and gives actionable decision rules.

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 discloses extensive behavioral details: two operational modes, response structure (leg-by-leg prices, spread in percentage points), safety fields (compatibility_warning with two distinct cases), temporal_alignment semantics, and skipped_cross_type/subtype counters. It also transparently states that most pre-mapped topics are not tradeable, which is honest about the tool's current 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 dense but well-organized: it starts with the core purpose, then explains modes, response, and safety fields. Each sentence adds new information – the 'SKIPPED_CROSS_TYPE' and 'TWO MODES' sections are structured with parenthetical detail. While quite long, it is justified by the tool's complexity, and the use of code formatting for fields helps readability. Not perfectly concise, but front-loaded and efficient.

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

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

With no output schema, the description carries the full burden of explaining return values. It thoroughly covers the response structure (leg-by-leg prices, raw probabilities, top_spreads_pp), safety fields (compatibility_warning, skipped_cross_type/subtype, temporal_alignment), and their meanings. For a tool with this complexity and nuance (non-equivalent bet shapes), the description is sufficient for an agent to understand what to expect and when to trust the result.

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 descriptions for all three parameters (100% coverage). The description adds semantic value by explaining how the parameters interact: topic as a shortcut, and kalshi_event_ticker/polymarket_event_slug as overrides. It also clarifies the valid topic values and gives examples. This goes beyond simple schema descriptions and clarifies the mode semantics.

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

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

The description 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 like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison. The two operational modes (topic shortcuts and explicit event IDs) are explicitly stated, leaving no ambiguity about what the tool does.

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

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

The description clearly explains when to use each mode: pre-mapped topics for quick access and explicit ticker/slug for custom pairings. It also warns that pre-mapped topics often return compatibility warnings, implicitly advising caution. However, it does not reference alternative tools (e.g., polymarket_arbitrage) or provide explicit 'when not to use' conditions beyond the compatibility warnings.

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

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

Annotations already cover readOnlyHint and destructiveHint. The description adds valuable context: scoping by identifier (anonymous IP, BYO key hash, account ID), the dual retrieval/listing behavior, and lifecycle pairing with remember/forget. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the primary action, then adds context and scoping. Every sentence earns its place with no redundancy.

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

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

Given the tool has only one optional parameter and no output schema, the description fully covers the retrieval and listing modes, scoping, and the remember/forget lifecycle. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic richness by giving concrete examples of key values ('target ticker, an address, prior research notes') and explicitly stating that omitting the key lists all keys, which reinforces the schema description.

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

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

The description clearly states a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It distinguishes from siblings by explicitly pairing with remember and forget, making the tool's role in the ecosystem clear.

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

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

It gives clear usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch' and names complementary tools (remember, forget). However, it lacks an explicit 'when not to use' statement, 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, openWorldHint, idempotentHint, and destructiveHint false. The description adds the sorting behavior ('newest DOI registrations first') and the domain (PANGAEA), which are not covered by annotations. This adds contextual behavioral information beyond 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 a single concise sentence that efficiently conveys the tool's purpose and behavior. Every word is meaningful, with no unnecessary filler or repetition.

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

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

For a simple list tool with 2 optional parameters, an output schema, and rich annotations, the description provides sufficient context. It states the resource and ordering, while the schema covers parameter details and defaults. No additional return format or pagination explanation is needed given 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?

Schema description coverage is 100%, so the schema fully documents both parameters ('days' and 'size'). The description does not add any additional meaning beyond the schema, so 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 states a specific verb ('published') and resource ('PANGAEA datasets'), and clarifies the ordering ('newest DOI registrations first'). This clearly distinguishes it from sibling tools like 'dataset' or 'search', which target specific datasets or general search.

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

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

The description implies use when the user needs recently published PANGAEA datasets, but does not explicitly mention alternatives or exclusions. It provides clear context ('most recently published') without saying 'use X instead', making it a clear context but not explicit 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 annotations declare readOnlyHint=true, but the description discloses that setting mark_read:true 'flag[s] returned events read so the next call only shows newer ones', which is a state mutation. This contradicts the read-only guarantee, creating an annotation contradiction. Other behaviors (payload fields, polling) are transparent but the conflict overshadows.

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 about five sentences, with some redundancy between 'Pull fired events' and 'Returns the most recent alerts'. It is front-loaded and structured with purpose, content, filters, mark_read, and alternative access, so it's suitably concise despite minor duplication.

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 explicitly listing return fields (source, citation_uri, raw event payload). It covers filtering, state behavior, polling, and an alternative URL, making it complete for the tool's complexity.

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

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

The schema already describes all five parameters, so the baseline is 3. The description adds value by giving an example type ('sec_8k'), clarifying the since parameter as ISO timestamp, and explaining mark_read's effect on future calls, pushing it above baseline.

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

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

The description opens with 'Pull fired events from your subscription feed', explicitly naming the verb and resource. It clarifies the return payload and differentiates from sibling tools like list_subscriptions by focusing on alert events, not subscription management.

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 explains this is for pulling alerts, mentions polling acceptability, and provides an alternative URL for scripts, giving context on when to call the tool. However, it does not explicitly name alternative tools or state when not to use it, so it's clear but not exhaustive.

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, openWorldHint, and idempotentHint annotations, the description discloses behavioral details like single parallel fan-out across SEC, GDELT/GNews, and USPTO; fallback logic; soft-failure due to API sunset; and the return format (changes[], total_changes, citation URIs). This is rich, non-obvious 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 every sentence contributes value: use cases, source fan-out, fallback, parameter format, output structure, and alternative tool. It is appropriately structured and front-loaded, though slightly long; the concentration of information could benefit from a brief separation of concerns, but it remains efficient.

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

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

Given the tool's complexity (multiple data sources, fallbacks, date parsing) and the absence of an output schema, the description is remarkably complete. It explains the return structure, source-specific behaviors, fallback triggers, and parameter formats, leaving minimal gaps for an agent to resolve.

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

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

The schema covers 100% of parameters, but the description adds meaningful semantics for 'since' by providing ISO date and relative shorthand examples ('7d', '30d', '3m', '1y') plus a recommendation ('Use 30d or 1m for typical monitoring'). It does not additionally elaborate on 'type' or 'value' beyond the schema, but the added since guidance moves it above the high-coverage baseline.

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

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

The description clearly identifies the tool as a 'change feed for a company in the last N days/weeks/months', with specific use-case examples like 'What's new with X' and 'latest on Y'. It also explicitly distinguishes itself from entity_profile ('Use entity_profile instead when you want the static profile'), setting it apart from at least one sibling and giving it a clear scope.

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

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

The description provides explicit when-to-use guidance through example queries, and explicitly names an alternative (entity_profile) for different needs. It also discloses fallback behavior (GDELT preferred, GNews when rate-limited or 5xx, USPTO soft-fail), which helps the agent make informed invocation decisions.

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 idempotentHint=true and readOnlyHint=false. The description adds valuable context about scoping by identifier, persistence differences between authenticated and anonymous sessions, and the key-value nature of storage. It does not mention overwrite behavior explicitly, but the idempotent hint covers that.

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, with the main purpose in the first sentence and supporting details following. Every sentence earns its place, providing practical examples and usage context without unnecessary fluff.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, usage, persistence behavior, and pairing with sibling tools. It is complete and leaves no significant gaps for the agent to select and 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?

Schema description coverage is 100%, so the parameters are fully documented in the schema. The description reinforces the key-value concept but does not add new parameter-specific details beyond what the schema already provides. Baseline 3 applies.

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

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

The description clearly states the tool saves data for later reuse, specifying the action ('Save data') and the resource ('key-value pair'). It distinguishes itself from siblings like recall and forget, which are explicitly mentioned as complementary 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?

It provides explicit when-to-use guidance ('Use when you discover something worth carrying forward') and names alternatives (recall, forget) for retrieval and deletion. This gives clear context for when to choose this tool over others.

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 significant behavioral context: cascading through multiple lookup endpoints, graceful degradation (if GLEIF/OpenFIGI unavailable, EDGAR still returns), labeling identifiers with source, and explicitly stating unresolved identifiers. 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 relatively long but well-structured. It starts with example queries, then states the core purpose, then details each type. The technical details about internal cascading and identity spine are relevant but could be streamlined. Every sentence adds value, but the length may slightly reduce scanability. It is front-loaded with the key message.

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 carries the burden of explaining return values. It describes that identifiers are labeled with source, unresolved ones are stated explicitly under 'unresolved', and for company returns CIK, ticker, LEI, FIGI, etc. For drug returns RxCUI, ingredient, brand, citation. This is sufficiently complete for an agent to understand the output structure, though a concrete example would improve it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema: it explains that 'type' can be 'company' or 'drug' and details what each returns. For 'value', it mentions that ISIN can be used for company type, and gives examples. The schema already includes examples, but the description adds context about the identity spine and cross-source lookups, justifying a 4.

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

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

The description clearly states the tool's purpose: resolve a user-spoken name to canonical/official identifiers. It provides specific examples ('What's the ticker for...', 'find the CIK for...') and explicitly says 'Use FIRST whenever you have a name but need an ID.' It distinguishes from siblings like compare_entities and entity_profile by focusing on name-to-ID resolution.

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 guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported types ('company' and 'drug') and what each returns. It does not explicitly state when not to use it or compare to alternatives, but the guidance is clear enough for the agent to decide. The mention of graceful degradation adds practical usage context.

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

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

Annotations already provide read-only and idempotent hints. The description adds valuable behavioral context: it probes each entity via ai_visibility_check, ranks by score, surfaces the most/least recognized, and returns a ranked list with score, confidence, and signal density. This goes beyond annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the main purpose, and contains no fluff. Every sentence adds value: what it does, how it works, and what it returns.

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

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

With no output schema, the description appropriately explains the return format (ranked list with score, confidence, signal density) and the subject/competitor narrative. It covers the core purpose, behavior, and parameters, making it complete for this 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 coverage is 100%, so the baseline is 3. The description adds extra semantics for the 'entities' parameter, explaining that the first entry is treated as the 'subject' for the narrative and the rest are competitors. This is not evident from the schema alone, raising the 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 clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the resource (AI visibility) and scope (multiple entities), and it distinguishes itself from the sibling ai_visibility_check by focusing on side-by-side comparison rather than single-entity checks.

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

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

It provides a concrete use case ('useful for competitive AI-marketing audits') and implies it is the right choice when comparing multiple entities. However, it does not explicitly state when not to use it or explicitly name alternatives (though mentioning ai_visibility_check as the underlying probe hints at that distinction).

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, and idempotent, but description adds substantial behavioral context: first bundlephobia measurement can take 5-30s, partial failures degrade gracefully, and sources_failed lists timed-out sources. This goes beyond the annotations without contradicting them.

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

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

The description is long, but every sentence earns its place: purpose, use cases, return shape, ecosystem scope, and failure behavior. It is front-loaded with the main intent, though the middle section is a run-on that could be split for readability.

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 is provided, so the description compensates by listing the exact summary fields, per-advisory detail, links, and alternative versions. It also covers edge cases like partial failures and timeout behavior, making it complete for an agent to invoke and interpret results.

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

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

Schema covers 100% of parameters with descriptions, including npm package name, scoped package support, and version defaulting behavior. The description does not add any new parameter-level details 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?

Description clearly defines the tool as a composite 'should I add this npm package' check, naming the specific data sources (deps.dev, bundlephobia) and output fields. This distinguishes it from the sibling tools, none of which focus on dependency evaluation.

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

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

Explicitly states when to use: whenever the agent asks about safety, popularity, size, or cost of adding a package. Also gives exclusion guidance (NPM only; other ecosystems fall under deps.dev:version directly), which helps route the agent correctly.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about the domain and return fields, but does not provide additional behavioral traits beyond what annotations already convey, so it does not significantly raise the transparency bar.

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

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

The description is two sentences, front-loaded with the core purpose, and contains only useful details like domain scope, returned fields, and example queries. There is no fluff or redundancy.

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

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

For a simple tool with full schema coverage, rich annotations, and an output schema, the description adequately covers what the tool does, what it returns, and when to use it. It is complete enough 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 descriptions cover 100% of the parameters, so the schema already documents from, size, and query. The description's example queries add no semantics beyond the schema's own examples, so it does not meaningfully compensate or augment 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 clearly states a specific verb and resource: full-text search of PANGAEA earth/environmental science datasets, and lists the returned fields. It is specific and distinct from a generic search, but it does not explicitly distinguish itself from sibling tools like search_within or facets.

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 concrete examples of when to use the tool ('Use for questions like "ocean temperature datasets"...') and defines the domain scope. It gives clear context for usage but does not mention exclusions or alternatives relative to sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context beyond these: returns character offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char overlapping windows, and caps input at 200K chars with truncation flagging. No contradiction with annotations.

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

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

Four dense sentences, each earning its place: core operation, use case/benefit, companion integration, and algorithmic/cap details. Front-loaded with the primary verb and resource, no wasted words despite the tool's complexity.

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

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

Despite no output schema, the description explains return values (passages with offsets and similarity scores), covers input limitations (200K chars, truncation), and provides an integration pattern. This is complete for a moderately complex tool with strong schema/annotation support.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context for the 'text' parameter (pass 'the text you already pulled' with examples like SEC 10-K body, article) and clarifies that query is natural language. It doesn't extend the 'limit' parameter beyond its schema description, but overall it elevates semantics above the schema alone.

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

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

The description uses a specific verb+resource ('Semantic search INSIDE a fetched record') and clearly distinguishes from siblings like 'search' (external search) and 'ask_pipeworx' (whole-document grounded Q&A). It states inputs (text + query) and outputs (top-N passages with offsets and scores), making the tool's 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?

Explicitly says 'Use when the record is too big to cram into the prompt' and provides an alternative/companion tool: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and integration guidance, exceeding the 'explicit alternative named' benchmark.

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 this as non-read-only and idempotent, but the description adds significant behavioral context: OAuth requirement with anonymous/BYO exclusion, phone verification and 10/day SMS cap, webhook HMAC signing and auto-disable after 10 failures, and the one-time delivery of the signing secret. These traits are beyond what annotations provide and set clear expectations.

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

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

The description is a dense paragraph that front-loads the core purpose in the first sentence and packs all critical details. While somewhat long, every clause contributes necessary information for a multi-type, multi-channel subscription tool. It could be slightly more scannable with lists, 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?

Given the tool's complexity (5 types, nested params, 4 delivery channels), the description covers all bases: return value, prerequisites, type-specific filtering, delivery channel behaviors, and operational limits. No output schema exists, but the description compensates by specifying the returned subscription ID and webhook secret. The tool is fully navigable without additional documentation.

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

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

Despite 100% schema coverage, the description enriches every parameter with concrete examples and constraints: type-specific params like items:['5.02'] for sec_8k, topic:'fed' for polymarket_edge, and delivery object validation (E.164, verified phone, HTTPS-only webhooks). This adds substantial meaning beyond the schema's brief 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 and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states the tool creates a subscription and returns an ID, distinguishing it from siblings like list_subscriptions and unsubscribe. The supported types and delivery channels further specify its unique role.

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, including prerequisites (Pipeworx OAuth account) and alternatives for pulling alerts (recent_alerts or registry URL). It does not explicitly name sibling tools for exclusion, but the context is strong and the supported types/delivery options imply appropriate use cases. A minor gap is the lack of explicit 'use this instead of X' 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?

Given the annotations already declare readOnly, openWorld, and idempotent hints, the description adds valuable extra context: the return structure (category-bucketed examples), the source (live catalog), and the behavior with and without arguments. This goes beyond the annotations without contradicting them.

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

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

The description is longer than average but every section serves a purpose: user-facing phrasing, return format, usage variations, and explicit 'when to use'. It is front-loaded with common queries and structured with clear information flow, though slightly verbose in the middle.

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

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

Despite no output schema, the description fully explains what the tool returns (category-bucketed examples with tool+argument shape) and how to invoke it (no args vs topic). For a discovery/onboarding tool with good annotations, this is complete and self-sufficient.

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

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

The schema fully documents the `topic` parameter, but the description adds meaningful guidance by giving example topics ('finance', 'pharma', 'betting') and explaining the effect of omitting it ('cross-category spread'). This enriches the schema without redundancy.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that suggests example questions, returned in category buckets, each with the exact tool and argument shape. This distinguishes it from siblings like ask_pipeworx or discover_tools by emphasizing its role as the starting point for learning what Pipeworx can do.

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

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

The description explicitly says to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and to learn how to call meta-tools, providing clear context and precedence. It also explains the optional `topic` parameter but does not explicitly contrast with alternatives like discover_tools, so it falls just short of a 5.

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

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

The description explains the row is deactivated not deleted, and historical events remain available via recent_alerts. This adds meaningful behavioral detail beyond the annotations' destructiveHint=false and idempotentHint=true.

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

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

Two sentences, front-loaded with the action, and every clause adds relevant context. No unnecessary words.

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

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

For a simple single-parameter operation with strong schema/annotations, the description fully covers the behavior, side effects, and post-condition. No output schema is needed for this tool.

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

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

Schema description coverage is 100% and the id parameter is well-documented as a uuid returned by subscribe. The description adds no new parameter semantics 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 'Cancel a subscription by id', a specific verb and resource, and clarifies ownership enforcement. This clearly distinguishes it from sibling tools like subscribe and list_subscriptions.

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

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

It states ownership is enforced, making it clear this tool only applies to the user's own subscriptions. It doesn't explicitly name alternatives, but the context is sufficient given the sibling tool list.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive, and the description adds substantial behavioral context: the dual fast-path/grounded-pipeline routing, the full verdict set, the critical distinction between could_not_verify (not evidence) and unsupported (no source), and the inclusion of pipeworx:// citations and reasoning. This goes well beyond the annotations, so 5 is 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 dense paragraph but every sentence earns its place: trigger phrases, usage guidance, routing logic, return value, and important caller caveats. It is front-loaded with the most actionable info and avoids fluff, making it efficient despite its length.

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

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

With no output schema, the description fully explains the return shape (verdict, value with citation, reasoning), covers all verdict meanings and error cases, and gives clear invocation context. The tool's complexity (two routing paths, multiple verdicts, open-world semantics) is matched by complete coverage, so 5 is warranted.

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 both params are already documented well. The description adds meaningful extra semantics for tolerance_pct: it overrides the tolerance implied by the claim wording and recommends 1–2 for hallucination detection, plus notes the default cap of 5. This is beyond the schema, so it deserves a 4.

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

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

The description opens with a set of natural-language triggers ("Is it true that…" / "fact check" / "verify the claim that…") and defines the resource as "natural-language claim verification against authoritative sources." The verb+resource is specific and clear, but it does not explicitly differentiate from sibling tools like ask_pipeworx_grounded or search, so it stops short of a 5.

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 "Use whenever the agent needs to check whether something a user said is factually correct," which is explicit guidance on when to use. It also explains the internal routing for company-financial vs. other claims. However, it provides no explicit when-not-to-use or named alternatives, so it earns a 4 rather than a 5.

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