art

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

Annotations already declare readOnly, openWorld, and idempotent hints, so the description builds on them by revealing important behavioral details: default model, external payment implications, API key forwarding, and return structure. This exceeds mere annotation repetition but lacks deeper details like rate limits or failure modes.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, the second covers model selection and costs, and the third summarizes output and use cases. Every sentence contributes without redundancy.

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

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

Given there is no output schema, the description compensates by naming the per-model response fields (score, confidence, signals, raw_response) and the combined view. It also provides practical context (default free model, BYO-key cost). However, it does not mention any limits on number of models or potential error conditions, leaving a minor gap for a tool with moderate complexity.

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

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

The input schema covers 100% of parameter descriptions, so the description does not need to add much. It does reinforce the meaning of '_apiKey' and the default model, but the schema already provides the necessary semantics. Thus the baseline score of 3 applies.

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

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

The description clearly states the tool's function with a specific verb ('probe'), resource (LLMs), and scope (score visibility 0-100 per model). It also includes distinct use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) that differentiate it from sibling tools.

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

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

It provides clear contexts for use (audits, brand checks, monitoring) and explains model options (default free workers-ai vs BYO-key Anthropic). However, it does not explicitly state when not to use it or name alternative tools, so it falls short of the highest bar.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses that the tool routes to the right tool, fills arguments, and returns stable pipeworx:// citation URIs. It also mentions performance ('one fast call') and operability ('works on every tier'), adding useful context not present in annotations. However, it omits some fine-grained behaviors like error handling or rate limits, but these are not critical given the non-destructive nature.

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

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

The description is dense and well-structured, front-loading the key directive ('PREFER OVER WEB SEARCH') and then providing scope, examples, and escalation paths. It is longer than the ideal, with some redundancy ('START HERE' repeats earlier advice), but every sentence conveys either use-case, behavior, or alternatives, so it remains efficient 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?

Given the tool's complexity (routing across thousands of sources) and the absence of an output schema, the description thoroughly explains what the tool does and what it returns (structured answer with citation URIs). It also covers edge cases by directing users to grounded or deep research tools when a different behavior is needed, making it contextually complete.

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

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

The input schema already provides 100% coverage with descriptions for all six parameters (mostly aliases for 'question'). The description adds value by giving concrete example questions ('current US unemployment rate', 'Apple's latest 10-K') that illustrate the expected natural-language input. This clarifies the semantics beyond the schema's dry alias descriptions.

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

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

The description clearly states the tool's function: it routes factual questions to the appropriate tool among 5,529 tools and returns structured answers with citations. It distinguishes itself from siblings by explicitly naming alternatives like ask_pipeworx_grounded and deep_research and by positioning itself as the default entry point.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for factual questions and lists trigger phrases ('what is', 'look up', etc.). It also states when to escalate to alternatives ('Step up only when needed') and names them, giving clear exclusion criteria.

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

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

The description goes beyond the annotations by disclosing that this is the experimental edge, that candidate routing improvements may be enabled live, and that the last candidate was retired. It also clarifies the fallback behavior ('Falls back to nothing — this IS a full working router'). This adds useful context without contradicting the readOnly/idempotent hints.

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

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

The description is concise: three sentences that efficiently convey the beta nature, the current state, usage instructions, and fallback behavior. No wasted words, and the most important information (beta, identical to stable) 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?

For a complex universal router without an output schema, the description provides necessary context: scope (5,529 tools), relationship to stable ask_pipeworx, current experimental status, and comparison behavior. It relies on ask_pipeworx for response shape, which is a reasonable reference and keeps the description complete without enumerating return values.

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

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

The schema already documents all six parameters as aliases for 'question' with clear descriptions and 100% coverage. The description adds only that it uses 'same arguments' as ask_pipeworx, which does not enrich the parameter meaning beyond the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description explicitly identifies this as a 'Beta version of ask_pipeworx' and a 'universal router' with the same set of tools, arguments, and response shape, clearly stating what it does. It distinguishes itself from the stable sibling ask_pipeworx by emphasizing its experimental routing improvements, avoiding any tautology.

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

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

Provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It also clarifies the current state (no active candidate, so it matches ask_pipeworx exactly), giving clear context for when to choose this tool over the stable alternative.

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

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

The description goes well beyond the annotations by detailing the exact success and refusal response structures, including refusal reasons, and discloses the cost and routing behavior. It adds context about using only tool-result content, which is critical for understanding the tool's guarantees.

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 serves a purpose: purpose, mechanism, return structure, use cases, and tradeoff. It is front-loaded with the core concept and contains no filler or redundant information, making it efficient and scannable.

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

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

Given the tool's complexity (routing across many tools, no output schema), the description provides a complete picture: return values, refusal reasons, when to use, and cost. It covers all essential operational aspects an agent needs to invoke and interpret the tool correctly.

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

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

Schema coverage is 100% with a well-documented 'question' parameter and aliases, so the schema already carries the parameter semantics. The description adds no additional parameter-specific detail, but the baseline of 3 applies since the schema is sufficient.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, distinguishing it from the sibling ask_pipeworx by emphasizing grounded extraction from tool results. It uses specific verbs like 'EXTRACTS' and 'returns' and describes the tool's unique value proposition.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), while naming the alternative tool. It also gives cost tradeoff (one extra LLM call), providing clear decision 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 already declare the tool read-only, idempotent, and non-destructive, so the description takes on the burden of explaining behavioral edge cases. It does so thoroughly, disclosing low-confidence short-circuits, blocked statuses, wide-spread tradeability flags, and cancellation-rule parsing, which are 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 lengthy but organized into CAPITALIZED sections that make it navigable. It front-loads the purpose and usage, and each section adds meaningful detail for a complex tool with no output schema. It's not concise, but it's structured and information-dense, earning a 4.

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

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

Given there is no output schema, the description compensates by detailing response shapes, resolver contract, parent-event extractor, news fields, safety mechanisms, and resolution-rule risk. It covers edge cases and blocking behavior thoroughly, 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?

Schema coverage is 100%, with each parameter fully described in the input schema, so the baseline is 3. The description adds context for the market parameter (slug/URL/question text) and fan-out examples, but these repeat or are implied by the schema. It doesn't explain depth or include_raw beyond what the schema already says.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' clearly identifying the verb, resource, and outcome. It distinguishes itself from sibling Polymarket tools by specifying use cases ('should I bet on X') and detailing the evidence-packet plus market-vs-model comparison output.

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

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

It explicitly states when to use the tool with the 'Use for' list, giving clear context. It doesn't name alternative tools or provide when-not guidance, but the fan-out examples and resolver contract further clarify its role relative to other Polymarket tools. This earns a 4 rather than 5 due to the lack of explicit exclusion statements.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses key behavioral traits: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric so 'largest' reads off the top, and return format with pipeworx:// citation URIs. This is rich, non-obvious context that annotations do not provide.

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

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

The description is somewhat long but front-loaded with example queries and a clear purpose statement. Every sentence adds unique value (data sources, sorting, citations, efficiency gains). It could be trimmed slightly, but it remains efficient and well-structured for a tool with two distinct modes.

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 covers return values ('paired data + pipeworx:// citation URIs'), data sources for both types, sorting behavior, and fiscal year handling. It also explains the tool's advantage over alternatives, making it fully self-contained for an agent to decide when and how to invoke it.

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

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

Though schema coverage is 100%, the description adds significant meaning: the 'type' parameter is tied to specific data fields (revenue, net income, cash, long-term debt for company; adverse-event counts, approval counts, trial counts for drug). It also clarifies that values are tickers/CIKs vs drug names, and gives concrete examples. This elevates understanding well beyond the raw schema.

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

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

The description clearly states a specific verb+resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It opens with example queries ('Compare X and Y' / 'X vs Y') that immediately establish intent, and distinguishes itself from sibling tools by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups.'

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also names the alternative approach (sequential lookups) and explains why this tool is better ('Replaces 8–15 sequential lookups'), making the usage context unmistakable.

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

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

Annotations already convey readOnly/idempotent hints, but the description adds substantial context: account and paid-tier requirements, not-open-web nature, 'never invented' gaps, fetchable citation_uri, contradictions[], semantic excerpting, and latency expectations. This goes far beyond the structured annotations and sets accurate user 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 long but every sentence earns its place: prerequisites, purpose, behavioral details, alternatives, depth modes, output format, and latency are all covered in a logical flow. It is front-loaded with the critical account requirement and immediately orients the user. No fluff or redundancy.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It enumerates the findings packet fields (verbatim evidence, confidence, source, fetched_at, citation), explains gaps[] and contradictions[], describes citation_uri fetchability, discusses semantic excerpting, and provides latency estimates. It leaves few unanswered questions for an agent deciding whether and how to invoke it.

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

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

The schema already documents both parameters with high detail (100% coverage), including full enum semantics for depth. The description adds valuable operational context—depth behaviors like 'gap recovery' and 'contradictions scan', plus the paid-tier constraint—but does not redefine parameter syntax. Since the schema does most of the heavy lifting, a 4 reflects the meaningful enrichment without overstating it.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and goes further to describe decomposition, parallel routing, and the findings packet. It explicitly distinguishes itself from open-web search and from the sibling tool ask_pipeworx, making its purpose unmistakable.

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

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

Provides explicit when-to-use/alternatives: 'If you are not signed in, use ask_pipeworx instead,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also covers depth selection rationale and the best-fit scenario ('Best for broad/multi-part questions'), leaving little ambiguity about when to invoke this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds meaningful behavioral detail: it returns top-N relevant tools with names, descriptions, full input schemas, and curated examples, all ready to call directly with no second schema lookup. This goes beyond the annotation baseline, though it does not cover rate limits or pagination.

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

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

The description is front-loaded with the core purpose, then provides a compact list of domains and return behavior. It is about three sentences and every clause adds useful context. The domain list is long but valuable for scoping the tool's coverage.

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 explaining the return format (top-N tools with names, descriptions, full schemas, curated examples, ready to call directly). It also enumerates the domains covered and clarifies the 'call first' behavior. This is sufficient for a meta-tool, though it could mention how to interpret relevance or handle empty 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?

The input schema has 100% coverage, documenting 'query' and its aliases (q, task, search, description) plus 'limit'. The description adds no new parameter-level semantics beyond the schema; it only indicates the query should be a natural language task description, which the schema already states. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task' and clarifies the discovery scope by enumerating domains like SEC filings, FDA drugs, FRED economic data, etc. It clearly differentiates from sibling tools by positioning itself as the meta-search/discovery layer rather than a domain-specific tool.

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

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

Explicit usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly tells the agent when to invoke this tool versus going directly to a domain tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds significant behavioral context: it fans out across multiple sources, returns specific fields, soft-fails for patents (USPTO sunset), uses GDELT→GNews fallback, and sorts results by period_end DESC. It also discloses that it makes one parallel call, which is a useful implementation detail.

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 example queries to help intent recognition, states the core purpose, gives preference guidance, lists sources and return fields, and ends with input format. Every sentence earns its place; the multiple paraphrases of 'tell me about X' are useful for recognizing user intent. The organization front-loads the most important information.

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

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

There is no output schema, so the description must explain return values. It does: lists cik, company_name, recent_filings (with URI scheme), fundamentals (with specific financial fields and sorting), patents (with soft-fail caveat), news (with fallback), and LEI. It also explains input constraints and the need for resolve_entity. This gives an agent enough context to invoke the tool correctly.

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

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

Schema coverage is 100% and both parameters are fully described in the schema. The description simply repeats the schema's value description (ticker or CIK, names not supported) without adding new semantic details. It does provide a concrete example ('AAPL', '0000320193'), but this is already in the schema. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call', specifying the action (profile/brief) and resource (US public company). It also distinguishes from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and references 'resolve_entity' for name-only inputs.

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: 'when the user asks for a holistic view'. Explicit when-not-to-use: 'names not supported (use resolve_entity first if you only have a name)'. It also states a clear alternative: 'single-pack SEC/XBRL/news lookups' are for narrower queries. This provides strong guidance for an AI agent.

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

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

Annotations already carry destructiveHint=true and idempotentHint=true, so the safety profile is clear. The description's 'Delete' aligns with this but adds only mild context (e.g., clearing sensitive data) beyond what annotations already disclose. No contradiction exists.

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

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

Two sentences with zero filler. The first sentence states the action, the second provides usage triggers and sibling pairing. Every word earns its place.

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

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

For a simple one-parameter tool with a complete schema and annotations covering destructiveness, the description covers purpose, usage, and workflow context. No output schema is needed for a delete action, and the agent can infer 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 fully describes the key parameter as 'Memory key to delete' with 100% coverage. The description's 'by key' adds no new semantic information, so the baseline of 3 is appropriate.

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

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

The description opens with a clear verb-object pair: 'Delete a previously stored memory by key.' This directly states what the tool does and distinguishes it from sibling tools like remember and recall, which handle storing and retrieving memories.

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

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

The description gives explicit when-to-use conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with remember and recall, which helps the agent understand the tool's role. However, it doesn't explicitly state when not to use it or name alternatives, so it falls short of a 5.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds meaningful process detail: it fetches the page, extracts title/description/key links, and emits a single text blob. This enriches the agent's understanding beyond the annotations, though it omits potential failure modes or rate limits.

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 and compact, with the first sentence stating the core purpose and target users, and the second adding process and use cases without redundancy. Every sentence earns its place.

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

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

For a simple two-parameter tool with strong annotations, the description covers purpose, process, output format, and use cases adequately. Minor omissions such as error handling for unreachable URLs are acceptable given the tool's 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 input schema fully describes both parameters (`url` and `max_links`) with examples and defaults, achieving 100% coverage. The description adds no extra parameter meaning, so the baseline of 3 applies.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a given URL, with specific extraction and formatting details. It does not explicitly contrast with sibling tools like scan_competitor_ai_presence, so it stops short of full differentiation.

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 lists three concrete use cases: getting a client's site indexed, drafting llms.txt for a project, and auditing a competitor's AI visibility. This gives clear context for when to use the tool, but it does not provide exclusionary guidance or mention alternative tools.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds value by listing the returned fields (title, artist, etc.) and image URL, giving insight into the output.

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 with the purpose front-loaded and no filler. Every sentence contributes essential information.

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

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

With one parameter, comprehensive annotations, an output schema, and a description covering return fields, the tool is complete for its simple read-only purpose.

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 object_id with an example. The description supplements it by noting the ID comes from search results, providing additional context beyond the schema.

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

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

The description clearly states the tool retrieves full details for a specific artwork, distinguishing it from search_artworks which lists results. The phrase 'from search results' positions it as a follow-up to 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?

It explicitly instructs to provide the object ID from search results, implying use after search_artworks. No exclusions are given, but the context is clear enough for correct tool selection.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description does not need to repeat those. It adds the behavioral nuance of returning the 'full list' (implying no pagination), but otherwise focuses on return content rather than deeper behavioral traits like ordering or limits.

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?

A single, front-loaded sentence that immediately states the action and resource. Every word adds value—no filler, 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?

For a zero-parameter, read-only list tool with rich annotations and an output schema, the description is fully adequate. It includes the institution (Metropolitan Museum of Art), the entity type (curatorial departments), and the return format (numeric ID), leaving no essential gap.

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

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

With zero parameters, schema coverage is trivially 100% and there is no parameter semantic burden. The description adds a helpful example of department names, which is the kind of contextual enrichment expected for a parameterless tool.

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 ('Return'), names the resource ('full list of Metropolitan Museum of Art curatorial departments'), and provides examples plus the output format (numeric department ID). This clearly distinguishes it from sibling tools like get_artwork or search_artworks.

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 implicitly tells an agent when to use this tool: whenever a complete list of Met department IDs/names is needed. It does not explicitly mention alternatives or exclusions, but the context is clear enough given sibling names and the straightforward purpose.

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

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

Annotations already declare readOnlyHint true and destructiveHint false, so the safety profile is covered. The description adds the list of return fields and clarifies the scope ('caller's active subscriptions'), providing useful context beyond annotations. It does not mention the include_inactive parameter behavior, but that is captured in the 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?

Two sentences, front-loaded with the purpose, then return fields, then usage context. Every sentence serves a distinct purpose with no unnecessary detail.

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

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

Given the tool's simplicity (one optional param, no output schema, strong annotations), the description is sufficiently complete. It covers purpose, return fields, and usage. The only minor gap is the lack of mention of include_inactive, but that is adequately documented in the 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%, and the single optional parameter include_inactive is fully described in the schema. The description does not add any additional meaning or syntax beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb 'List' and resource 'subscriptions'. It also enumerates the returned fields, distinguishing it from siblings like subscribe and unsubscribe which perform mutations.

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

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

Explicit guidance is given: '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 it relative to subscribe/unsubscribe, though it does not explicitly name alternative tools or state when not to use it.

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

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

With all annotations false, the description carries the full behavioral burden and delivers richly: rate limit (5/day), free/no quota, daily digest read, returns claim_token without account, token can be used later to check status/resolution. 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 every sentence adds practical value: purpose, usage triggers, exclusions, message guidance, token mechanism, rate limit. It is front-loaded with the core purpose and well-organized, though slightly verbose.

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 feedback tool with no output schema, the description fully explains return behavior (claim_token), resolution status, and roadmap impact. It covers all necessary aspects: when, how, exclusions, limits, and follow-up, making it complete for agent 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 coverage is 100%, so baseline is 3, but the description adds meaningful usage context: claim_token must be used alone with no other arguments, message should reference Pipeworx tools/packs and not paste end-user's prompt, and context is optional structured info. This goes beyond the schema's descriptions.

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

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

The description explicitly states the tool's purpose with a specific verb ('Tell the Pipeworx team') and resource, and clearly distinguishes it from sibling tools by focusing on feedback about Pipeworx tools rather than other MCP servers or research/query tools.

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

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

Provides explicit when-to-use scenarios (bug, feature, data_gap, praise) and when-not-to-use (different MCP server, with specific instruction to file elsewhere). Also gives follow-up usage via claim_token and guidance on what not to include (end-user's prompt).

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it explains the data source (analytics-engine), privacy (no PII), and caching behavior (5min-1h), enhancing transparency without contradicting annotations.

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

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

The description is well-structured with a front-loaded summary, a concise return specification, a numbered list of use cases, and additional context. Every sentence earns its place; no unnecessary fluff.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the essential aspects: what it does, when to use it, data source, privacy, and caching. It is fully self-contained.

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

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

The schema already provides a thorough description of the 'window' parameter with enums and explanations. The description text merely mentions the windows ('24h, 7d, or 30d') without adding meaning, so the schema carries the full semantic burden.

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 returning trending call data ('top tools, top packs, and total call volume') with a specific time window. It distinguishes itself from siblings like discover_tools by focusing on aggregated usage signals rather than general discovery.

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

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

The description provides explicit use cases for when to consult this tool, such as discovering hot data sources or validating a canonical tool choice. It gives clear context but does not explicitly mention exclusions or name alternative tools.

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

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

Annotations declare readOnlyHint etc., but the description adds rich behavior: the Jaccard similarity threshold (≥0.30), placeholder slug filtering, the fill check against live CLOB depth with realizable_edge_pp ≤ 0 warning, and the 'do not trade it' advice. This goes far beyond annotations and never contradicts 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?

Although lengthy, every sentence carries operational weight. The use of CAPS labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) structures dense technical content cleanly. No filler or repetition; 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 compensates by specifying the response shape: opportunities[] fields, partition_check fields, skipped_low_similarity, thin_legs[]. It also covers edge cases (placeholder >20% returns null, fill-check conditions). This is 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?

Schema covers 100% of params with descriptions, but the description adds substantial value: example slugs, URL acceptance, mode semantics (event walks child markets, topic searches related events), and the seed question examples. It turns the schema's bare definitions into actionable usage guidance.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings by mentioning polymarket_fill_risk for custom sizing and describing unique modes (trending_scan, event, topic) not seen in other tool names.

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

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

Explicit guidance is given: 'Call with NO args for a trending_scan... pass event for... or topic for...' It recommends event mode for specific markets, explains cross-event mode catches patterns single-event misses, and ends with 'For custom sizing use polymarket_fill_risk' — a clear alternative. This is textbook when-to-use vs 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 annotations (readOnly, idempotent), the description discloses important behavioral details: edges are 'NET of slippage,' Kelly is 'capped at 0.25,' there's a '24h-move warning' that flags when recent price movement exceeds the edge, and segment-specific behavior like 'placeholder-slug filter' and 'rare-by-design' for concentrated longshots. It also reveals caching behavior ('Cached 1h at the KV level keyed on all knobs') and explains why diagnostics are included ('so callers can see WHY a segment is empty'). This is exemplary transparency.

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

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

The description is lengthy but well-organized, using section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL, _diagnostics) to make the dense content scannable. It front-loads the primary purpose and then elaborates, with minimal fluff. The length is justified by the complexity of the tool, but a few sentences could be tightened, preventing a 5.

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

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

For a complex tool with 9 parameters, no output schema, and multiple model families, the description covers all essential aspects: response structure (by_segment, fed_candidates, _diagnostics), model-specific logic (lognormal barrier, GDELT ratio, per-sport α), tradeability filters, caching, and exclusions. It even explains the rationale for excluding Fed signals. This is a near-complete picture for an agent to know when and how to 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?

The input schema already provides 100% coverage with detailed descriptions for all 9 parameters, so the baseline is 3. The description adds value by explaining the interaction between knobs (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and clarifying the subtle relationship between min_kelly and min_partition_leg_kelly ('Partition arbs always return kelly_fraction_half=0 at the parent level by design...'). These insights go beyond the schema's per-parameter descriptions.

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

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

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which clearly identifies the tool's function (scan and return) and its unique value (Pipeworx data disagreement). It names the resource (Polymarket markets) and explains the intended use case ('what should I bet on today'), distinctly differentiating it from sibling tools like polymarket_arbitrage. Explicit mention of the 'FIVE MODEL FAMILIES' further specifies the output 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 states the tool is 'Built for "what should I bet on today"' and explains how it saves agents from 'paging hundreds of markets.' It provides explicit knob guidance ('min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and exclusion criteria ('Fed bets surface here, excluded from ranking'). However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so it falls short of a perfect 5.

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

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

Even though annotations already declare read-only and idempotent hints, the description adds substantial behavioral context: snapshot TTL limits, cache-miss writing behavior, gaps in snapshot_dates meaning no scan, decay computed from daily closes not intraday, and the signed interpretation of edge_pp_net. This goes far 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 long but efficiently organized with clear sections (Args, RESPONSE, LIMITS). Every sentence adds essential information, and the opening sentence front-loads the core purpose. There is no wasted verbiage; the structure earns its length for such a complex tool.

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

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

With no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates), field meanings, and limitations. It covers the tool's complexity thoroughly, including trend values, decay calculation, and TTL constraints, leaving no major gaps 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?

The schema already documents both parameters with defaults and allowed values (100% coverage), so the description adds little beyond repeating the defaults and calling 'window' a 'snapshot family'. The description does provide context on how window maps to polymarket_edges, but this is minor additional value over the schema.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry built from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools by focusing on temporal tracking rather than just current edges, explicitly contrasting fresh vs. old edges.

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

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

The description gives clear context on when to use the tool (to understand edge persistence/decay) and even mentions 'the median lifespan is your competition clock', implying a competitive analysis use case. However, it does not explicitly name alternatives or provide when-not-to-use guidance, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral context: it 'walks the ladder' and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, capture_ratio, profit_usd, thin_legs[], forced_directional_risk, etc. It explains the mechanism of capturing overround/underround and the risk of partial basket fills, which goes well beyond the structured annotations.

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

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

The description is long but well-organized into SINGLE-MARKET and BASKET sections, using colons to separate mode from details. It is front-loaded with the core purpose and includes no redundant filler. The final use-case sentence lands the 'when to use' guidance effectively.

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 (two modes, no required schema fields, no output schema), the description enumerates the return fields for both modes, names verdicts, and highlights failure modes like thin_legs and forced directional risk. It provides enough information to invoke the tool correctly without needing to guess at outputs or behavior.

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

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

Schema descriptions cover 100% of parameters, but the description adds essential meaning beyond them: it states 'REQUIRES one of `market` or `event`', explains that `size_usd` is interpreted as settlement notional in basket mode ('shares per leg; each share pays $1'), and clarifies default side behavior for each mode. This significantly reduces ambiguity.

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 pairing: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a pre-trade risk assessment: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.'

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

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

Provides explicit when-to-use guidance: before arbitrage signals or edge trades above ~$500, and warns why partial fills are dangerous. It also outlines two usage modes (single-market vs basket/partition) and explains how to select the appropriate `market` or `event` parameter, and what each side means in each mode.

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 true, so the safety profile is covered. The description adds critical behavioral context: compatibility_warning conditions, temporal_alignment meaning, skipped_cross_type/subtype semantics, and the warning that most pre-mapped topics return warnings — all beyond the annotations.

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

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

The description is long but as a single dense paragraph it front-loads the core purpose and packs each sentence with distinct info (modes, output, safety fields, caveats). It's slightly verbose but every sentence earns its place given 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 must fully specify return semantics, and it does: leg-by-leg prices, matched spreads, top_spreads_pp, compatibility_warning cases, temporal_alignment, and skip counters. It covers edge cases and limitations comprehensively.

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 parameter descriptions are good. The description adds the mode concept, explaining how topic maps to auto-fetch and how explicit overrides work, giving meaning beyond the schema.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', a specific verb+resource that clearly distinguishes it from sibling tools like polymarket_arbitrage (single-venue) and polymarket_edges. It also details two input modes and what output to expect.

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

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

The description explains two usage modes (topic shortcuts vs explicit tickers) and sets expectations with 'pre-mapped ≠ tradeable'. It doesn't explicitly name alternative tools, but the context is clear and the warning about compatibility_warning helps users know when not to rely on the output.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by disclosing scoping to the caller's identifier (anonymous IP, BYO key hash, or account ID) and the listing behavior when the key is omitted. 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 three tightly constructed sentences, each earning its place: functionality, usage context, and scoping/complementary tools. It is front-loaded with the primary verb and resource, with zero waste.

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 retrieval tool with strong annotations, the description covers behavior, parameter semantics, scoping, and relationship to siblings. No additional return-value documentation is needed given the clarity of 'retrieve a value' and 'list all saved keys'.

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

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

Schema coverage is 100% with a clear parameter description. The tool description adds further meaning by providing concrete examples of keys (ticker, address, research notes) and explains how omitting the key triggers list-all behavior, enriching the bare schema definition.

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 (retrieve/list) and resource (previously saved values), distinguishing it from sibling tools by explicitly naming remember and forget as the complementary operations. The dual behavior (value retrieval vs. listing all keys) is clearly specified.

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

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

The description gives a concrete use case ('look up context the agent stored earlier') and provides explicit alternatives/companions ('Pair with remember to save, forget to delete'). It makes clear when to use this tool versus other memory operations.

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

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

The description contradicts the readOnlyHint annotation by revealing that setting mark_read:true will flag returned events as read, altering the persisted feed. This is a state-changing behavior, yet the annotation claims the tool is read-only. The contradiction is severe and overrides any additional behavioral context the description provides.

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

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

Four sentences, front-loaded with the primary action. Every sentence adds value: data payload, filtering options, mark_read behavior, polling, and an alternative endpoint. No filler or repetition.

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

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

Despite lacking an output schema, the description fully covers the return values (source, citation_uri, raw payload), relevant parameters, and usage context. It even explains the side-effect of mark_read and the availability of an HTTP endpoint. For a simple read tool, this is highly complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches this by explaining the semantics of mark_read ('flag returned events read so the next call only shows newer ones') and giving a concrete type example ('sec_8k'). It also clarifies the 'since' parameter as an ISO timestamp, adding meaning beyond the schema's terse 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 'Pull fired events from your subscription feed' – a specific verb and resource that clearly states the tool's core function. It further details what each alert carries and how filtering works, making the purpose unmistakable and distinct from siblings like list_subscriptions or recent_changes.

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

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

The description clearly sets the context: this is for reading alerts from the subscription feed, and explicitly notes that polling works fine. It also provides an alternative (the direct HTTP endpoint) for scripts/dashboards, implicitly directing agent use to this tool. It does not explicitly contrast with sibling tools, but the context is unambiguous enough for a 4.

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

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

Adds rich behavioral context beyond the readOnly/idempotent annotations: fans out to SEC EDGAR, GDELT→GNews with fallback on rate-limit/5xx, and USPTO with soft-fail due to API sunset. Also details the return structure (changes[], total_changes, citation URIs), 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 long but every sentence earns its place—natural-language triggers, parallel-call efficiency, per-source fan-out details with fallback, date formats, and output shape. It is front-loaded with the primary use case and progressively detailed.

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

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

Given there is no output schema, the description thoroughly covers the return format (structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs). It also explains data sources, date filtering, and the sibling alternative, making it self-sufficient for an agent.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description repeats the 'since' format examples but adds no new parameter-level meaning beyond what the schema provides; baseline 3 is appropriate.

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

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

Description explicitly defines the tool as a 'change feed for a company in the last N days/weeks/months' and lists natural-language triggers ('What's new with X', 'updates on Acme'). It distinguishes from sibling entity_profile by stating 'Use entity_profile instead when you want the static profile,' making the resource and scope 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 trigger phrases for when to use ('What's new with X', 'latest on Y') and explicitly names an alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This is explicit when-and-when-not guidance.

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

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

Discloses important behavioral traits not covered by annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. The idempotentHint is consistent, and the description adds key-value storage semantics.

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

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

The description is four sentences, each earning its place: purpose, usage trigger, storage mechanics, and companion tools. Well structured and front-loaded with the core action.

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

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

For a simple two-parameter tool with strong schema and annotations, the description fully covers usage scenarios, retention behavior, and relationships to siblings. No output schema is needed, and no gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the value can be 'any text' and that storage is 'scoped by your identifier,' reinforcing the key-value model beyond the schema's field descriptions.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It uses a specific verb ('save') with a clear resource (data/memory) and differentiates from sibling tools like recall and forget by explicitly pairing with them.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, address, preference). It also references alternatives/complements: 'Pair with recall to retrieve later, forget to delete.'

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses significant behavioral traits: it cascades through multiple internal endpoints, labels identifiers with sources, explicitly reports unresolved identifiers, and degrades gracefully when external sources are unavailable. This adds substantial value over annotations alone.

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

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

The description is dense and information-rich, starting with example queries and then providing structured details. It is longer than a minimal description but every sentence adds value (sources, fallbacks, unresolved handling). It could be slightly trimmed but remains well-organized.

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 lacking an output schema, the description thoroughly covers return behavior (source labels, unresolved identifiers, graceful degradation) and edge cases. It fully explains what to expect, 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?

Although the schema coverage is 100%, the description enriches parameter meaning by detailing what each type ('company', 'drug') returns, giving specific input examples for the 'value' parameter (ticker, CIK, name; brand/generic), and explaining fallback behavior. This goes well 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 clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers needed by other tools. It uses a specific verb ('resolve') and resource ('entity name'), lists concrete example queries, and distinguishes itself from siblings by positioning it as the first step when an ID is needed.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' This gives clear when-to-use guidance. It does not explicitly name alternatives or when-not-to-use scenarios, so it misses the full 'when/when-not/alternatives' bar, but provides clear 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 declare readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: it probes each entity, ranks by score, and returns a ranked list with score/confidence/signal density. This goes beyond the annotations by describing the mechanism and output shape, though it doesn't cover edge cases like rate limits.

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

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

The description is two sentences, with the first sentence front-loading the core purpose and the second adding mechanism and use case. There is no redundant or filler content; each 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?

The tool has no output schema and moderate complexity (4 params, one required). The description compensates for the lack of an output schema by specifying return fields, and it gives usage context. It could mention model options/API key requirements, but those are covered by the schema and annotations. The description is sufficiently complete for an agent to select and invoke it.

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

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

The schema provides 100% coverage of all 4 parameters with descriptions. The description reinforces the entities semantics (your brand + N competitors) and mentions ranking, but does not add any parameter detail that is not already in the schema. Per the rubric, baseline is 3, and no extra credit is warranted.

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

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

The description states a specific verb ('Compare AI visibility') and resource ('across multiple entities side-by-side'). It further distinguishes itself from the sibling ai_visibility_check by explicitly naming it as the underlying probe and adding ranking/side-by-side comparison. This is a clear, differentiated 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 a clear use case: 'Useful for competitive AI-marketing audits' with an example question. It does not explicitly state when not to use it or name alternatives, but the context implies single-entity checks would use ai_visibility_check instead. That meets the standard for a 4, not a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description goes beyond by revealing internal fan-out behavior, partial failure degradation, a 5-30s latency caveat for first bundlephobia measurement, and the sources_failed field. This is exactly the kind of behavioral context that helps an agent set 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 single dense paragraph, front-loaded with purpose and usage, then detailing return fields and failure modes. Every sentence contributes useful information 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?

Despite lacking an output schema, the description enumerates all return components (summary block fields, advisory detail, links, alternatives) and covers edge cases (timeouts, partial failures). For a composite tool with two external services, this is complete.

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

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

Schema coverage is 100%, so baseline 3. The description adds minimal extra parameter semantics beyond the schema; it mentions scoped package acceptance and provides an example version, but these are already in the schema. No additional meaning is provided.

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: composite check for 'should I add this npm package'. It clearly distinguishes from siblings by focusing on npm dependency evaluation using deps.dev and bundlephobia, which no other sibling tool appears to cover.

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

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

Explicitly states when to use ('whenever an agent asks is X safe / popular / small') and provides an alternative path for other ecosystems (deps.dev:version directly). This gives clear decision 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description goes well beyond by disclosing the ranking order (title matches first, artist/culture second, full-text last) and that each result includes a matched_on field. It also lists the returned fields, providing rich behavioral detail unavailable from annotations alone.

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

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

The description is two sentences, front-loaded with purpose and examples, followed by behavior and return fields. Every clause adds value with no redundancy or filler.

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

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

With a full output schema (mentioned as present), robust annotations, a simple two-parameter input schema, and the description adding ranking and matched_on behavior, the tool is fully specified. The agent can correctly select and invoke this tool without additional elaboration.

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 query and limit fully documented. The description adds examples and explains how the query is interpreted (subject, artist, or keyword), but this largely mirrors the schema. It does not significantly enhance parameter understanding beyond what is already in the structured fields.

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

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

The description clearly states what the tool does: 'Search the Met's collection by subject, artist or keyword' with concrete examples. It distinguishes the tool from siblings by focusing on collection search and including ranking logic, which differentiates it from get_artwork, get_departments, and search_within.

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

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

The description gives clear context for when to use the tool ('Search the Met's collection') and provides example queries. However, it does not explicitly mention alternatives or when not to use, such as pointing to get_artwork for specific artwork retrieval, 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?

Beyond annotations (readOnly, idempotent), the description reveals mechanics: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings with 500-char overlapping windows, and has a 200K char cap with truncation flagged. This adds substantial operational context and does not contradict annotations.

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

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

Three dense sentences: purpose, usage scenario, and technical limits. Every sentence earns its place, front-loaded with the core action, and avoids fluff. Highly efficient and well-structured.

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

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

For a search tool with no output schema, the description fully covers return format (top-N passages with offsets/scores), input expectations (text + query), and edge cases (truncation). It also situates the tool within the broader workflow via the sibling mention. The agent has everything needed to select and invoke correctly.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds context for 'text' (e.g., 'already pulled' and truncation cap) and implies 'limit' via 'top-N passages.' It reinforces schema definitions without redundantly repeating them, but the added value is modest.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' providing a specific verb and resource. It clearly distinguishes from sibling tools like ask_pipeworx by emphasizing searching within already-fetched text, with concrete examples (SEC 10-K, article).

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 this tool: 'Use when the record is too big to cram into the prompt.' It names a complementary sibling (ask_pipeworx_grounded) and explains how they pair, giving clear 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 declare idempotentHint=true, but the description says 'Create... Returns the new subscription id,' implying each call creates a new subscription and is not idempotent. This directly contradicts the idempotentHint annotation, forcing a score of 1 per the rubric.

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

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

The description is dense but well-structured: it starts with the main purpose, then required account, then supported types and delivery channels. Every sentence carries necessary information for a complex tool with multiple subscription types and delivery options. It is lengthy, but the length is justified by the breadth of functionality.

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 3 params, nested objects, no output schema, and a variety of subscription types and delivery channels, the description covers all essential aspects: return value (subscription id), auth requirements, all supported types with examples, all delivery options with constraints, and even webhook failure behavior (auto-disabled after 10 consecutive failures). It is remarkably complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by providing concrete examples for each subscription type (e.g., items:["5.02"] = officer change, params:{topic:"fed"}), explaining delivery channel constraints (verified phone, 10/day cap, webhook HMAC signing), and detailing the always-on feed behavior. This goes beyond what the schema already describes.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream,' giving a specific verb and resource. It clearly distinguishes from sibling tools like unsubscribe and list_subscriptions by focusing on creation, and mentions 'Returns the new subscription id' to clarify the outcome.

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 an explicit prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions),' which tells users when not to use it. It also names an alternative for consuming alerts: 'pull via recent_alerts or GET registry.pipeworx.io/alerts.json,' giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: it returns category-bucketed example questions with exact tool + argument shape, drawn from a live catalog, and explains behavior with no args vs topic filtering. 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 a single dense paragraph of four sentences. It is front-loaded with example queries and then provides concise explanations of return value, parameter usage, and when to use. Each sentence earns its place, though a bulleted list could improve scannability without adding 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 explains what the tool returns (category-bucketed example questions with exact tool + argument shape). It also covers parameter behavior, usage context, and the relationship to meta-tools. For a simple one-parameter tool, this is complete.

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

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

The input schema provides 100% coverage for the single optional topic parameter, including allowed values and the 'omit for cross-category spread' guidance. The description echoes this with examples but does not add any new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape to answer them. It is specific about the resource ('what can I ask Pipeworx') and distinguishes itself from siblings by positioning as the 'FIRST' tool to use when unfamiliar with Pipeworx.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains the no-args vs topic behavior. It does not explicitly name an alternative tool like discover_tools for comparison, but the 'USE FIRST' instruction provides clear prioritization.

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 (idempotent, non-destructive, mutating), the description explains the soft-delete behavior ('deactivated, not deleted') and the impact on historical events. This adds valuable context about the data lifecycle and aligns perfectly with the destructiveHint=false annotation.

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

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

Two sentences, front-loaded with the action, and every sentence adds value: the first covers the core operation and constraint, the second explains data behavior. 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?

The description covers the action, ownership constraint, and soft-delete behavior, which is sufficient for a simple tool. It omits return-value details, but since there is no output schema and the operation is straightforward, this is a minor gap rather than a major deficiency.

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 fully describes the single 'id' parameter with high coverage, and the tool description does not add meaningful detail beyond the schema. Baseline 3 is appropriate given the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes this from siblings like subscribe and list_subscriptions, and the ownership constraint adds clarifying detail about the 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 clear usage context: you can only cancel your own subscriptions, and it references recent_alerts for historical consequences. It does not explicitly name alternative tools or when-not-to-use scenarios, but the ownership limitation serves as a key constraint.

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

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

Beyond annotations, the description details the two execution paths, the full verdict enum, and the critical semantics of 'could_not_verify' (not evidence) and 'unsupported' (no source covered). It also discloses the return payload (actual value, pipeworx:// citation, reasoning), which is not present in 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?

Despite being longer than typical descriptions, every sentence contributes: trigger phrases, routing rules, verdict semantics, and caller warnings are cleanly separated with dashes and a bolded IMPORTANT. The structure is front-loaded with purpose and usage, making it easy to scan.

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

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

With no output schema, the description fully covers return values (verdict types, actual value, citation, reasoning) and explains the two non-standard outcomes (could_not_verify, unsupported). It also addresses the multi-step alternative it replaces, making the tool comprehensible in context.

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

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

The input schema already fully describes both parameters with 100% coverage. The description adds useful context by giving example claims and clarifying that tolerance_pct overrides the claim wording's implied tolerance, but this is supplementary rather than essential.

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

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

The description opens with explicit trigger phrases ('Is it true that…', 'fact check') and states the core function: natural-language claim verification against authoritative sources. It distinguishes this tool from siblings by explaining it replaces 4–6 sequential calls and handles both structured financial and general factual claims.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and gives concrete routing rules (company-financial claims via SEC EDGAR, else grounded pipeline). It also tells callers when the tool is a shortcut by noting it replaces sequential NL parsing → entity resolution → data lookup → comparison.

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