Mercury Number

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description complements by detailing the output structure (per-model score, raw_response), the default model, and the BYO key mechanism for Anthropic. No contradictions.

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

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

Four sentences, front-loaded with the core action, each sentence adding unique value. No redundancy or fluff.

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

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

Given no output schema, the description adequately explains return format and use cases. Could mention performance considerations but overall sufficient for a 4-param read-only 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 all parameters with descriptions (100% coverage), but the description adds valuable context: default model is free, _apiKey needed for Anthropic, and the entity description is enriched with examples. This goes beyond baseline 3.

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

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

The description clearly states the tool probes LLMs for visibility scoring, with a specific verb (probe) and resource (LLMs), and distinguishes from siblings like ask_pipeworx by focusing on scoring and multiple models.

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 lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), but doesn't provide explicit when-not-to-use or alternatives. However, the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false for safe read-only behavior. The description adds context beyond annotations: it returns structured answers with stable citations, works on every tier, and is a 'one fast call' default entry point. It does not contradict annotations, and it clarifies the routing behavior and output format.

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

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

The description is longer than average, but every sentence earns its place: it covers preference over web search, covered domains, routing behavior, output format, usage triggers, examples, tier compatibility, and alternatives. It is front-loaded and structured as a flowing but logically sectioned text. Slightly verbose, but the complexity of the tool justifies the length.

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

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

For a meta-tool with no output schema, the description is remarkably complete: it explains what it returns (structured answer with citation URIs), when to use it (default for factual questions), when to use alternatives (grounded, deep_research), and even covers breaking-news scenarios. It also notes it works on every tier, addressing accessibility. No significant gaps are apparent for an agent to decide whether to invoke this tool.

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

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

Schema coverage is 100% with six parameters, all aliases for 'question', which already have descriptions. The description adds value by explaining the question should be a natural-language factual query and provides examples of query formats across domains (e.g., 'current US unemployment rate', 'Apple's latest 10-K'). This exceeds the baseline of 3 for high schema coverage by clarifying the expected input semantics and query styles.

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: routing factual questions to 5,462 tools across 1,419 verified sources and returning structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by describing their specific use cases, and it names the tool as the default entry point for most questions. The verb 'ask' is contextualized as a router, not a simple lookup.

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 with trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and concrete examples. It also states when to step up to alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. It even addresses breaking-news coverage, effectively setting exclusions and alternatives.

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

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

The description adds significant behavioral context beyond annotations: it explains live candidate routing testing, the retirement date of the last candidate, current exact parity with ask_pipeworx, and that it is a full working router with no fallback. Annotations already declare read-only/idempotent, so this enriches operational transparency without contradiction.

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

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

The description is information-dense and front-loaded with 'Beta version.' Each clause adds value: same tools/arguments/response, candidate testing status, usage instruction, and clarification of no fallback. It is slightly longer than strictly necessary but every sentence earns its place.

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

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

For a complex universal router with no output schema, the description explains what it is, current state, how to use it, and its relationship to ask_pipeworx (same response shape). This is enough to select and invoke correctly, though it relies on prior knowledge of ask_pipeworx for response format details.

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

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

Schema description coverage is 100% with all parameters (question plus five aliases) documented. The description only says 'same arguments as ask_pipeworx,' adding no unique parameter semantic value beyond the schema, so the baseline 3 applies.

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

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

The description clearly identifies the tool as the beta/experimental edge of ask_pipeworx, stating it is an identical universal router with the same 5,462 tools, arguments, and response shape. It explicitly distinguishes it from the stable ask_pipeworx sibling by noting candidate routing improvements and current parity.

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 it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router to decide merges. This provides clear context for when to use it, though it does not detail when not to use it or mention alternatives like ask_pipeworx_grounded.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description discloses refusal reasons, return format, evidence quoting, and the extra LLM call cost, which are not captured in structured fields. It also details the internal workflow (routing, fetching, extracting) and exact success/refusal payloads.

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 not bloated; it packs purpose, behavior, return format, and usage guidance into a few sentences, with all sentences contributing value. The structure flows logically from definition to mechanics to usage recommendation.

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

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

No output schema exists, but the description compensates by fully specifying the success and refusal return shapes and relevant trade-offs, making it self-contained for agent decision-making. It also covers cost, use cases, and alternatives within the context of sibling tools.

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

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

The schema already covers all 6 parameters with descriptions of aliases for the question, providing 100% coverage. The description doesn't add new parameter-level details beyond restating that it's a natural language question, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool is a 'Hallucination-resistant answer mode' that routes, fetches, and extracts answers from tool results, distinguishing it from ask_pipeworx by its evidence-based extraction and refusal behavior. The verb 'extracts' and resource 'answer' precisely define its function.

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

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

It explicitly instructs to use this tool when answers will be quoted, cited, or acted on and the agent must not invent facts, and to prefer ask_pipeworx for casual lookups. This provides a clear decision rule and names the alternative.

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

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

Annotations already set readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description goes far beyond, detailing fan-out logic, response shapes, resolver contract (match confidence levels, alternatives, suggestions), parent event extraction, news fallback fields, safety checks for low-confidence/closed/illiquid markets, and resolution-rule risk. No contradictions.

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

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

Well-structured with clear sections (fan-out examples, response shapes, resolver contract, etc.). Each part adds distinct value. Slightly long but appropriate for the tool's complexity. Front-loaded with purpose and usage.

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

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

Despite no output schema, the description thoroughly explains return value shapes (result.market, result.analysis, result.evidence) and critical fields like market_match_confidence, parent_event, news fields with fallback info, and edge warnings. Covers many edge cases (low-confidence, closed markets, wide spreads, cancellation rules). Sufficient for correct agent usage.

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% (all 3 parameters described). The description adds value beyond the schema by explaining the 'market' parameter can be slug, URL, or question text, and clarifies the trade-off between 'quick' and 'thorough' depth, plus when to pass include_raw=true. This context aids correct invocation.

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

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

Description opens with a specific verb+resource ('Research a Polymarket bet') and clearly distinguishes from siblings by focusing on pulling Pipeworx data for a single bet, resolving market, classifying, fanning out, and returning evidence. Siblings like ask_pipeworx or polymarket_edges serve different purposes.

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 lists three use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), provides input format examples, and gives fan-out examples per category. However, it lacks explicit when-not-to-use guidance or alternative tool recommendations for overlapping queries.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds key context: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. Minor omission of potential latency or error handling prevents a 5.

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 structured with example queries first, followed by technical details. It is informative but slightly verbose; the emphasis on 'ALWAYS PREFER' could be condensed. Still well-organized and front-loaded.

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

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

Given the tool's complexity (two entity types, multiple data fields) and no output schema, the description covers data sources, sorting, and return format (paired data + URIs). Lacks explicit listing of returned fields, but otherwise sufficient for an agent to understand what to expect.

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%, but the description adds essential meaning: clarifies what each entity type retrieves (company: financials; drug: adverse events, approvals, trials) and how to format values (tickers/CIKs vs drug names). This goes beyond the schema's basic 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 performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call. It provides specific trigger phrases ('Compare X and Y', 'X vs Y') and distinguishes it from sequential lookups, making the 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?

Explicit guidance is given: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' The description lists common user queries that should route to this tool, leaving no ambiguity about when to use it.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral context: latency (15-60s), paid plan requirement for depth:'thorough', citation URI resolvability, explicit gaps[] never invented, contradictions[] for deeper depths, and semantic excerpting of long records. This goes far beyond annotation defaults and contains no contradiction.

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

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

The description is long but extremely information-dense, covering account requirements, usage guidance, tool mechanics, return format, and latency. It is front-loaded with the account prerequisite and alternates between guidance and technical details. While every sentence earns its place, a more structured layout would improve scannability; still, it is concise relative to 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?

Even without an output schema, the description details the findings packet (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), explains error handling (empty gaps for unsupported topics), latency expectations, and second-hop iteration behavior. This provides a complete picture for an agent to decide 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?

Schema covers 100% of parameters, including detailed depth semantics, so baseline is 3. The description adds the paid-plan requirement for depth:'thorough' and connects depth levels to latency and behavioral differences (hop iteration, contradiction scan), slightly enriching parameter understanding beyond the schema.

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

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

The description states a specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' with decomposition into facets and parallel routing. It also distinguishes itself from siblings (ask_pipeworx for single lookup/news), so purpose clarity is excellent.

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-not-to-use, and alternatives are provided: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING... prefer ask_pipeworx', and even account-tier guidance ('If you are not signed in, use ask_pipeworx instead'). This covers usage context, exclusions, and named alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds behavioral context: returns top-N tools with full schemas and examples, ready to call. No contradictions. A small gap is lack of mention of pagination or rate limits, but not critical here.

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?

Description is front-loaded with the main purpose. Each sentence serves a purpose: lists domains, explains return value, provides usage guidance. Could be slightly more concise but remains effective.

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

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

Given the tool's complexity (6 params, no output schema), the description adequately covers what the tool does, what it returns (names, descriptions, schemas, examples), and when to use it. Missing details like exact return format but output schema absence makes this acceptable.

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

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

Schema coverage is 100%, so baseline is 3. Description goes beyond: explains that query accepts multiple aliases (task, q, search, description) and includes natural language examples. This adds 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 'Find tools by describing the data or task,' which clearly specifies the action (find) and resource (tools). This differentiates it from sibling tools that perform operations on data rather than discovering capabilities.

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

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

The description explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists example domains and tasks, giving clear guidance on when to use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, establishing safety. The description adds valuable behavioral context: parallel fan-out across multiple sources, specific data returned, and a note about the patents API sunset (soft-fail). This goes beyond the annotations by detailing scope and failure modes.

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

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

The description is front-loaded with trigger phrases and key details, but it is somewhat lengthy. However, every sentence adds necessary information (e.g., data sources, return fields, limitations). Minor redundancy (e.g., repeating 'names not supported') could be trimmed, but overall it is 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?

Given the tool's complexity (multiple data sources, no output schema), the description comprehensively covers what the tool returns (cik, company_name, recent_filings with URIs, fundamentals, patents with sunset note, news, LEI). This is sufficient for an agent to understand the output and make effective use of the tool.

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

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

Schema coverage is 100% and already describes the parameters well. The description adds value by reinforcing that 'value' accepts ticker or zero-padded CIK, and explicitly warns that names are not supported. This clarifies usage beyond the schema's description, earning an above-baseline score.

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

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

The description clearly states the tool's purpose: providing a full cross-source profile of a US public company in one parallel call. It lists specific user intents ('Tell me about X', 'research Acme') and explicitly distinguishes itself from chaining single-pack lookups, making the purpose unambiguous and distinctive from siblings.

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

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

The description provides explicit when-to-use guidance ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when-not-to-use ('names not supported — use resolve_entity first if you only have a name'). This clearly helps the agent decide between this tool and alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows this operation is destructive and idempotent. The description adds no further behavioral context beyond the basic deletion action, so it meets the baseline with no contradiction.

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

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

The description is two sentences long, front-loaded with the purpose, and every sentence is essential with no wasted words.

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

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

For a simple tool with one parameter, no output schema, and annotations covering destructive behavior, the description fully and adequately specifies the tool's function and 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 has 100% coverage with a clear description for the only parameter 'key' ('Memory key to delete'). The tool description does not add additional meaning beyond the schema, so score is baseline 3.

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

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

The description clearly states 'Delete a previously stored memory by key,' specifying the verb (delete) and resource (memory), effectively distinguishing it from sibling tools like 'remember' and 'recall'.

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

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

It provides explicit guidance on when to use: 'when context is stale, the task is done, or you want to clear sensitive data,' and even mentions pairing with 'remember' and 'recall' for 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 mark it as read-only, idempotent, and non-destructive. Description adds internal steps (fetch, extract title/description/key links, emit markdown), providing extra behavioral context.

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

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

Three sentences covering purpose, process, and use cases. No wasted words; front-loaded with 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?

With no output schema, description clarifies output format (text blob for site-root/llms.txt). All essential behavior is covered for a simple read tool.

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

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

Schema covers 100% of parameters. Description does not add format or syntax details beyond schema, but implies usage for URL and max links. 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?

Explicitly states it generates an llms.txt file for any URL, with clear verb and resource. Distinct from all sibling tools which cover different domains.

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?

Lists three concrete use cases (indexing clients' sites, drafting own llms.txt, auditing competitors). Implicitly tells when to use it, though no direct exclusions or alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so safety is clear. The description adds return field details but no additional behavioral traits 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 extremely concise (two sentences) with no wasted words, front-loading the action and return information.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description provides sufficient context about what is returned and when to use the tool.

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

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

Schema coverage is 100% with a well-described boolean parameter 'include_inactive'. The description does not add any extra meaning beyond what the schema already provides.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the return fields. It distinguishes from siblings 'subscribe' and 'unsubscribe' by implication as the complementary listing tool.

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

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

The description provides concrete use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. However, it does not explicitly state when not to use it or provide 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?

The description states 'Get a random number,' implying non-deterministic behavior, while annotations set idempotentHint=true, suggesting the same input yields the same output—a contradiction. The description does not clarify the randomness or how the optional sign parameter affects the result. Annotations already declare readOnlyHint and destructiveHint, but the contradiction undermines 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 two sentences, front-loaded with the core action and output, followed by usage guidance. Every sentence adds value, with no redundancy or fluff.

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

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

Given the tool is simple (one optional param, output schema exists, annotations provide safety info), the description is mostly complete: it explains purpose, return format, and usage context. The only gap is the unresolved contradiction between randomness and idempotency, which leaves agents unsure about determinism.

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

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

The schema describes the single optional parameter 'sign' with an enum and a humorous description. Schema coverage is 100%, so the description adds no additional parameter meaning. Baseline score of 3 is appropriate as the schema handles semantics adequately.

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 gets a random number (1-100) with astrological justification, specifying the verb 'get', the resource 'random number', and the unique context of Mercury's zodiac position. It distinguishes itself from the sibling tools, none of which are number generators.

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 when you need a number with Mercury retrograde insights or cosmic reasoning,' providing clear guidance on when to use the tool. However, it does not explicitly mention when not to use it or compare to alternatives, though no alternative number tool exists among siblings.

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

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

Annotations are all false, providing no behavioral signals, so the description carries the burden. It discloses the rate limit ('Rate-limited to 5 per identifier per day'), the quota exemption ('Free; doesn't count against your tool-call quota'), and how feedback is consumed ('The team reads digests daily'). It also instructs on content format ('don't paste the end-user's prompt'). Minor gaps remain about auth/privacy, but overall strong disclosure.

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

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

The description is ~150 words but every sentence serves a distinct purpose: scope definition, usage triggers, exclusion for other servers, disambiguation, content rules, roadmap impact, and operational constraints (rate limit, quota). It is front-loaded with the core purpose and well-organized, making it informative without being bloated.

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 parameters, a nested object, and no output schema, the description covers purpose, usage scenarios, exclusions, content guidelines, rate limit, and quota. It is nearly complete, though it does not mention the immediate response/acknowledgment after submission. This is a minor gap given the asynchronous nature implied by 'digest daily'.

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

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

Schema coverage is 100% with descriptions for all parameters and enum values, so baseline is 3. The description adds value by mapping the 'type' values to concrete triggers (bug/data_gap/praise) and providing message content guidance (be specific, don't paste user prompt). This enhances the parameter semantics beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb and resource, and explicitly lists the types of feedback (bug, feature/data_gap, praise). This distinguishes it from the sibling research/query tools, which all serve different functions.

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

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

The description provides explicit when-to-use triggers ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well') and a clear exclusion with an alternative ('if the tool came from a different MCP server... file it with that server instead'). It also offers a disambiguation heuristic ('Not sure? Pipeworx tool names are the ones this connection lists').

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

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

Annotations already cover safety (read-only, idempotent). Description adds value by disclosing caching behavior (5min-1h), data source (CF analytics, no PII), and aggregate nature, going beyond annotations.

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

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

Three sentences plus a bullet list front-load purpose and uses. Efficient but slightly verbose with 'Self-aggregating signal' phrase; still 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?

No output schema exists, but description adequately explains return values (top tools, packs, volume). Caching info and window semantics complete the picture for a simple tool.

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

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

Schema coverage is 100% with enum and description. The description reinforces window semantics with guidance on short vs long windows, adding 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 clearly states the tool returns 'top tools, top packs, and total call volume' over time windows, distinguishing it from sibling tools like 'discover_tools' or 'ask_pipeworx' by focusing on trending data from other agents.

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?

Three explicit use cases are provided (discovering hot sources, confirming popular tools, checking alignment) with context for window choice, though no direct exclusions or comparisons to specific siblings.

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

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

The description discloses many behavioral traits beyond annotations: scanning up to 200 markets, child market walks, partition checks, placeholder filtering, fill check against live depth, and conditions for not trading. All consistent with readOnlyHint and idempotentHint.

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 very detailed and front-loaded with purpose. It is somewhat verbose but every sentence adds value for a complex tool. Could be slightly more structured (e.g., bullet points), but the density is justified.

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

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

Given no output schema, the description fully documents the response structure (opportunities array, partition_check object, fill check results) and all edge cases (Jaccard similarity threshold, placeholder filter, thin legs). Complete for a complex arbitrage tool.

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

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

The description enriches parameter meaning far beyond the input schema. For event mode, it details child market processing and partition checks; for topic mode, it explains cross-event scanning, Jaccard similarity, and placeholder filtering. Schema coverage is 100% but description adds critical context.

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

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

The description clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes from sibling tools like polymarket_edge_tracker and polymarket_fill_risk by specifying the unique arbitrage detection approach.

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 explains when to use no args (trending_scan), event mode, or topic mode. It mentions cross-event mode catches patterns single-event misses, and directs custom sizing to polymarket_fill_risk, providing clear usage guidance.

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

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

The description goes far beyond annotations, detailing caching (1h KV), response structure including diagnostics for empty segments, exclusion of Fed bets from ranking, warning about edge being priced in, and detailed model behavior. Annotations already declare readOnly and idempotent, which aligns.

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 overly verbose, containing highly technical details (e.g., specific alpha values for tennis/soccer/MMA) that may not be necessary for tool selection and invocation. While front-loaded with the core purpose, the length could hinder quick parsing by an agent.

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

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

Despite lacking an output schema, the description thoroughly explains the response top-level structure, what each opportunity contains, and why segments might be empty. Combined with good annotations and comprehensive parameter descriptions, it provides complete contextual guidance for a complex tool.

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

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

The input schema covers 100% of parameters with clear descriptions. The tool's description adds extra context about how parameters interact (e.g., min_partition_leg_kelly vs min_kelly) and the tradeable-edge knobs, providing value beyond the schema alone.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and explicitly targets 'what should I bet on today'. However, it does not differentiate from sibling tools like 'polymarket_arbitrage' or 'polymarket_edge_tracker', which could create confusion for the agent.

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 context ('agents discover opportunities without paging hundreds of markets') implying a discovery use case, but it does not explicitly state when to use this tool versus alternatives (e.g., polymarket_arbitrage, polymarket_edge_tracker) or 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?

The description adds significant behavioral context beyond annotations: explains the response structure (tracked, expired, snapshot_dates), how decay is computed (daily closes, net of slippage), and data gaps. No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is verbose, with a long RESPONSE section. While it is structured with clear sections (args, response, limits), it could be more concise without losing 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?

Given the tool has 2 optional parameters and no output schema, the description fully explains the response structure and data interpretation. It covers tracked/expired arrays, snapshot dates, and limitations, making it complete for this complexity.

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

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

Schema description coverage is 100%, but the description adds meaning beyond the schema: default values, clamp ranges, and interpretation of the 'window' parameter. This adds value for agent invocation.

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

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

The description states the tool's purpose with a specific verb ('answers how long has this edge existed and is it shrinking?') and clearly distinguishes it from sibling tools like polymarket_edges by focusing on persistence and decay telemetry rather than current edges.

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

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

It explicitly describes what the tool answers and contrasts with fresh edges. Limitations such as 60-day snapshot TTL and data gaps are provided. However, it does not explicitly state when not to use it or give direct alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description does not need to reiterate safety. It adds useful context about the check behavior (walks ladder, returns verdict) and the risk of partial fills. However, it does not mention rate limits or authentication needs, but those are implicit.

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 clear sections: core purpose, mode details, parameter explanations, and usage guidance. Every sentence adds value, though it is somewhat verbose. It is front-loaded with 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?

Given the lack of an output schema, the description thoroughly explains all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). It also covers the risk of partial fills and directional exposure.

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

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

Schema coverage is 100%, yet the description adds significant meaning beyond the schema: it explains the two modes (single-market vs basket), default values, and how `size_usd` is interpreted differently (max spend vs target proceeds vs settlement notional). It also clarifies the `side` parameter's auto-detection for basket mode.

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

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

The description clearly states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and lists specific return fields. This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk assessment.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why theoretical overround is not capturable on thin books and warns that partial basket fills convert arb into unhedged directional positions. Also specifies that one of `market` or `event` is required.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral context: it explains the two modes, the compatibility_warning scenarios (non-equivalent bet shapes and semantic mismatch), temporal_alignment constraints, and skipped_cross_type/subtype counters. It also notes that pre-mapped topics often return warnings, managing expectations. 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 well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. While slightly verbose, every sentence adds value given the tool's complexity (cross-venue spread with many edge cases). Could be trimmed slightly, but overall effective.

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

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

Despite no output schema, the description fully covers the response structure: leg-by-leg prices, matched spreads, safety fields (compatibility_warning with two cases, temporal_alignment, skipped counters). It also explains the meaning of various fields, making the agent well-informed about what to expect. This is exemplary 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 coverage is 100% with each parameter already described (e.g., topic lists the 10 shortcuts in its description). The description adds context about the two modes and override behavior but does not significantly enhance the meaning beyond the schema's property descriptions. According to the rubric, for high schema coverage (>80%), baseline is 3, and this 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage (intra-venue) by specifying the cross-venue nature and the two modes (topic shortcuts vs explicit tickers). The verb 'get' or 'compute' is implied, and the resource (spread) is well-defined.

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 guides when to use each mode: `topic` for 10 pre-mapped shortcuts, and explicit tickers for custom pairings. It also warns that real cross-venue spreads are rarer and that most pre-mapped topics return compatibility_warning, setting appropriate expectations. Additionally, it explains safety fields that indicate when spreads are not meaningful (e.g., temporal misalignment, non-equivalent bet shapes).

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, destructiveHint. Description adds value by explaining pairing with remember/forget and scoping to identifier, which is beyond annotations.

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

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

Three sentences, no wasted words. Front-loaded with core action. Every sentence adds value.

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

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

Covers scoping, usage context, and companion tools. No output schema, but description does not need to explain return format for a simple retrieval tool. Acceptable.

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

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

Schema coverage is 100%, but description adds: 'omit the key argument to list all saved keys' – clarifying behavior beyond schema's 'omit to list all keys'.

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?

Clearly states the tool retrieves a saved value or lists keys, distinguishing it from siblings (remember, forget) by explicitly naming them. Verb 'retrieve' with resource 'memory' is specific.

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

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

Explains use case: looking up stored context without re-deriving. Mentions scoping. Lacks explicit when-not-to-use or alternatives beyond siblings, but context is clear.

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

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

Annotations declare readOnlyHint:true and idempotentHint:true, but the description reveals that setting mark_read:true mutates state (flags events as read), contradicting both hints. This adds important behavioral context 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 concise, with no wasted sentences. Key information is front-loaded, and each sentence contributes meaning: purpose, returned fields, filter options, side effect of mark_read, and alternative access.

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

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

Despite the lack of an output schema, the description fully explains what is returned (source, citation_uri, payload). It covers filtering, the mark_read side effect, and suggests alternative use cases (polls, scripts), making it complete for a read-oriented tool.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds value by providing an example for type ('sec_8k') and explaining the behavioral effect of mark_read, going beyond the schema.

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

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

The description clearly states the tool's purpose as pulling fired events from the subscription feed, specifying returned fields (source, citation_uri, raw payload). This distinguishes it from sibling tools like subscribe or list_subscriptions.

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

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

The description provides context for polling use and mentions an alternative REST endpoint for scripts/dashboards. However, it does not explicitly compare to other sibling tools or specify when not to use this tool.

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

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

The annotations provide readOnlyHint (true) and idempotentHint (true), but the description adds significant behavioral context: fans out to multiple sources, GDELT→GNews fallback, USPTO soft-fails, returns structured data with citation URIs. No contradiction with annotations.

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

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

Description is concise (about 100 words), front-loaded with example queries, and uses a clear logical flow. Every sentence is necessary—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?

Despite no output schema, the description explains the return structure (grouped changes, total count, citation URIs), covers fallback behavior, references sibling tool alternatives, and accounts for API sunset. Complete for a multi-source change feed tool.

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

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

Schema coverage is 100%, baseline is 3. The description adds extra meaning: for 'since' it explains ISO vs relative shorthand and gives examples; for 'value' it specifies ticker or CIK; for 'type' it notes only 'company' is supported. This adds value beyond the schema.

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

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

The description clearly states the tool provides a 'change feed for a company' with specific example queries like 'What's new with X' and 'latest on Y'. It distinguishes from the sibling tool 'entity_profile' by saying 'Use entity_profile instead when you want the static profile.'

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

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

The description explicitly tells when to use this tool vs the alternative 'entity_profile', and provides guidance on the 'since' parameter with examples like 'Use "30d" or "1m" for typical monitoring.' It also describes fallback behavior, giving clear usage instructions.

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 idempotence and non-destructiveness. Description adds valuable context: memory scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. No contradictions.

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

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

Five sentences, front-loaded with main purpose. Every sentence adds value 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 only two simple parameters, no output schema, and sibling tools, the description fully covers usage, lifecycle, and pairing.

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 100% with clear descriptions. Description adds semantic value by providing example key naming conventions and explaining value content (findings, addresses, preferences).

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, with specific examples (ticker, address, preference). It distinguishes from sibling tools recall and forget.

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

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

Explicitly says when to use: when discovering something worth carrying forward. Mentions pairing with recall and forget, providing clear 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 read-only, open-world, idempotent, and non-destructive hints. The description goes beyond these by detailing exact return fields (e.g., ticker + CIK + company_name for company; RxCUI + ingredient + brand for drug), input flexibility (ticker, CIK, or name), auto-disambiguation, citation URI patterns, and internal cascading through endpoints. This adds significant behavioral context 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 and front-loaded: it starts with intuitive example queries, then states the core purpose, provides a usage directive, and organizes type details under SUPPORTED TYPES. Every sentence adds useful information, and the formatting makes 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 compensates by specifying return values for each type, including citation URI patterns and input acceptance. It also covers edge cases like auto-disambiguation and internal cascading. Given the tool's low complexity (two parameters), this is a complete and actionable description.

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

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

The input schema already provides 100% coverage: it describes the type enum and the value format for company (ticker, CIK, or name) and drug (brand or generic name). The description restates this information and adds only a minor nuance about auto-disambiguation, which is more behavioral than parameter-specific. Since schema coverage is high, 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 resolves names to canonical identifiers, with specific examples like "What's the ticker for…" and "find the CIK for…". It explicitly distinguishes itself from siblings with the directive "Use FIRST whenever you have a name but need an ID," and lists supported entity types with concrete outputs.

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: "Use FIRST whenever you have a name but need an ID" and notes it replaces 2-3 manual lookups. However, it does not explicitly name alternative tools for cases where an ID is already available, nor does it state when not to use the tool, so it lacks the explicit exclusions/alternatives required for a 5.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals the mechanism: probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. It also notes the first entity is treated as 'subject' for narrative. This adds valuable behavioral context not in annotations.

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

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

The description is three concise sentences: first states purpose, second explains mechanism, third gives use case. No redundant information; each sentence earns its place. 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?

Given 100% schema coverage and comprehensive annotations, the description fills remaining gaps by explaining the output format (ranked list with specific fields) and the treatment of the first entity. The tool is fully understood for selection and invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context for the 'entities' parameter, specifying that the first entry is the subject and rest are competitors. For other parameters, the schema already provides sufficient description.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It includes a specific use case example, effectively distinguishing it from the sibling ai_visibility_check (single entity) and compare_entities (generic).

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 provides a use case: competitive AI-marketing audits with an example question. It implies when to use (compare multiple entities) versus alternatives like ai_visibility_check, though no explicit when-not-to-use or exclusion list is given. The context is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: fans out across deps.dev and bundlephobia, handles partial failures gracefully (bundlephobia first measurement takes 5-30s), and returns a specific summary block. This goes 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 a single, information-dense paragraph. It efficiently conveys purpose, usage, behavior, and return structure. Could be slightly more structured, but no wasted sentences.

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

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

No output schema, but the description thoroughly enumerates the return summary block components (is_latest, license, published_at, advisory_count, bundle_kb_min, etc.) and mentions additional info like per-advisory detail, links, and alternative versions. This is comprehensive for a composite tool.

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

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

Schema coverage is 100% with descriptions for both parameters (package and version). The description adds minimal extra meaning: clarifying ecosystem (npm) and that version defaults to latest. 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: a composite check for npm packages covering license, advisories, version history, and bundle size. It specifies the verb 'scan' and resource 'dependency' and distinguishes itself from potential alternatives by mentioning ecosystem limitations.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides context on ecosystem (NPM only) and alternatives (PyPI etc. via deps.dev:version).

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 (readOnlyHint, idempotentHint, destructiveHint=false), the description discloses embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K), and truncation behavior. No contradictions with annotations.

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

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

The description is concise (4 sentences) and well-structured: core purpose first, usage context second, technical details last. Every sentence provides essential 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?

Given 3 parameters, no output schema, and complexity of semantic search with offsets, the description covers all needed aspects: input, output (passages with offsets and scores), technical details (embeddings, windows, cap), and truncation handling. Text 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?

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the 'text' parameter as 'document text to search inside', 'query' as 'natural-language query' with examples, and 'limit' as 'max passages to return' with defaults and range. This enhances understanding beyond the schema.

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

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

The description clearly states the verb 'search' and resource 'inside a fetched record', and distinguishes from sibling tools by specifying it's for large records that don't fit in the prompt. It also mentions pairing with ask_pipeworx_grounded, reinforcing its specific role.

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

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

The description explicitly advises using when the record is too large to cram into the prompt, and suggests pairing with ask_pipeworx_grounded. While it doesn't list alternative tools for small records, the guidance is clear and contextual.

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 (idempotentHint=true), the description details important behaviors: requires OAuth account, anonymous/BYO cannot persist, delivery channel specifics (verification, daily cap, webhook signing secret returned once). This adds significant context.

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

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

The description is well-structured but somewhat lengthy. It front-loads the core purpose and then details types and delivery channels. Every sentence adds value 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?

The description is highly complete, covering auth, types, parameters, delivery channels, and behavioral details. However, it omits error handling and idempotency behavior, which could be useful.

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 100% schema coverage, the description adds substantial meaning by explaining each subscription type's parameters (e.g., sec_8k items codes) and delivery options, making the tool easier to use correctly.

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 subscription to a live-data event stream and returns a subscription ID. It distinguishes from siblings like unsubscribe and list_subscriptions.

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

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

The description specifies prerequisites (OAuth account), supported types, delivery channels, and constraints like phone verification and SMS cap. It provides good context for when to use the tool, though it could explicitly contrast with alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it returns example questions and is non-destructive, but doesn't significantly extend beyond annotations.

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

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

Front-loaded with purpose, well-structured with variations and usage. Slightly long but 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?

Comprehensive for a simple tool: covers when to use, what it returns (examples with tool shapes), optional parameter behavior, and context as onboarding entry point.

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 description adds value by listing possible topic values and explaining behavior when omitted.

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

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

Description clearly states it is the onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly says to use this FIRST when unsure of Pipeworx capabilities or to learn meta-tools. Specifies when to pass topic vs. omit for full spread.

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 behavioral context beyond annotations: ownership enforcement, deactivation (not deletion), and preservation of historical events via recent_alerts. 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?

Two concise sentences covering essential information without fluff. First sentence is action and ownership, second explains deactivation behavior.

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 one parameter, no output schema, and simple semantics, the description adequately covers purpose, usage constraints, and outcome. Complements sibling tools.

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%; description adds that the id comes from subscribe, but does not significantly expand on the schema's own description. Meets baseline for high coverage.

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

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

Description clearly states the action (Cancel a subscription) and the resource (by id), with details on ownership and deactivation behavior, distinguishing it from sibling tools like subscribe and list_subscriptions.

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

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

States ownership enforcement and that it only cancels own subscriptions, and mentions deactivation rather than deletion. Implicitly guides against using for others' subscriptions, but could be more explicit about when not to use.

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

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

The description adds significant behavioral details beyond annotations: it explains the internal pipeline (SEC EDGAR vs grounded), the verdict types, and that it replaces multiple sequential calls. It does not contradict annotations.

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

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

The description is informative but somewhat long. It is front-loaded with examples and structured logically. A slight trimming could improve conciseness, but it is efficient for the complexity.

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

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

Despite no output schema, the description thoroughly explains return values (verdicts, actual value, citation, reasoning). Parameter coverage is complete, and the complex behavior is well documented. 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%. The description adds context for tolerance_pct (overrides implied tolerance, default behavior) and explains the claim parameter as natural-language input. This adds value beyond the schema.

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

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

The description clearly specifies the tool's purpose: verifying factual claims against authoritative sources. It provides example queries and distinguishes between company-financial and other claims, differentiating 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?

The description explicitly states to use it when checking factual correctness. It explains the internal routing for different claim types, but does not explicitly say when not to use it, though the context implies alternatives like deep_research for broader research.

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