Pixabay

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context beyond that: it discloses cost implications ('you pay Anthropic directly'), explains the default model, and specifies the return structure per model. This is more than minimal and builds on 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?

Three sentences, front-loaded with the core purpose, then model details, then return format and use cases. Every sentence earns its place with no redundancy or filler.

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

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

The description covers the return format (per-model fields + combined view) despite no output schema, and communicates the key behavioral nuances (free default, cost-bearing Anthropic option). It's missing deeper interpretation of 'confidence' and 'signals', but for a probe tool with annotations, this is a reasonably complete picture.

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

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

Schema coverage is 100%, so all parameters are described. The description adds extra semantics by explaining the functional relationship between models and _apiKey (default vs. optional Anthropic trigger), and clarifies the entity scope. This goes beyond the schema's field-level descriptions, earning above baseline.

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

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

The description uses a specific verb ('Probe') and resource ('one or more LLMs') and clearly states the output (visibility score 0-100 per model). It distinguishes itself from siblings like ask_pipeworx by focusing on visibility measurement rather than question-answering, and from scan_competitor_ai_presence by applying to any entity, not just competitors.

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') and explains model selection and API key usage (default free Workers AI, optional Anthropic with BYO key). It doesn't explicitly name alternative tools for when not to use it, but the sibling list and context make the intended scenarios clear.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds valuable behavior beyond these: it routes the question, fills arguments, returns structured answers, and uses stable pipeworx:// citation URIs. It does not disclose possible failure modes or rate limits, but this is not required given the annotation coverage.

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

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

The description is long but well-structured and front-loaded with the most important directive: PREFER OVER WEB SEARCH. The domain list and examples are lengthy but they serve concrete usage guidance and help an agent recognize suitable questions. It is verbose, but nearly every sentence contributes to selection and invocation.

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 single-required-parameter tool with full schema coverage and no output schema, the description covers the main things an agent needs: what it does, when to use it, how it behaves, and what form the answer takes (structured-with-citations). It doesn't describe edge cases like empty results or unsupported question types, but this is a minor gap for such a broad routing tool.

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

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

Schema description coverage is 100%, so the schema already documents the single 'question' parameter and its aliases. The description adds useful examples and clarifies that the input is natural language, but it doesn't provide significant semantic detail beyond the schema. 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 states a specific verb and resource: it is the tool that routes natural-language questions to 5,801 underlying data tools and returns structured answers with citation URIs. It explicitly differentiates itself from siblings by being the default entry point and preferring over web search, and it lists ask_pipeworx_grounded and deep_research as alternatives.

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

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

The description gives explicit when-to-use guidance: it is marked as PREFER OVER WEB SEARCH, should be used whenever the user asks 'what is', 'look up', 'find', etc., and it is called START HERE for most questions. It also states when NOT to use it and names the step-up alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions.

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

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

Beyond the read-only/idempotent annotations, the description discloses that this is an experimental edge with candidate routing improvements enabled live, that no candidate is currently active, and that it currently matches ask_pipeworx exactly. It also clarifies 'Falls back to nothing — this IS a full working router,' preventing the misconception that it is a stub.

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 definition, then current state, usage, and a clarifying note. Every sentence adds distinct information with no redundancy.

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

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

For a router with no output schema, the description provides the essential call context: it is a full working router, identical to ask_pipeworx currently, and safe per annotations. The required question parameter and aliases are fully covered by the schema, and the experimental status is clearly flagged.

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

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

Schema coverage is 100% and the schema already documents question plus five aliases. The description only says 'same arguments' without adding parameter-level detail, so it does not improve on what the schema already provides.

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

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

The description opens with 'Beta version of ask_pipeworx: identical universal router' and specifies the exact scope: same 5,801 tools, same arguments, same response shape. This clearly identifies it as an experimental variant of the sibling ask_pipeworx and distinguishes it from other 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?

It explicitly instructs 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It names the stable alternative and gives a selection condition, though it does not enumerate when-not-to-use cases or mention 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?

The description goes far beyond the annotations by disclosing the routing pipeline, the extraction constraint (ONLY from tool result), the exact deterministic success object, and the full refusal reason enum. None of this is visible in the annotations or schema, so it substantially improves transparency. The annotations readOnlyHint/openWorldHint/idempotentHint are consistent with the described read-only, grounded behavior.

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

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

Every sentence earns its place: it front-loads the purpose, explains the process, enumerates exact success/refusal outputs, and closes with a cost-based routing rule. Though dense, the length is justified because the tool is high-stakes and needs to be understood before invocation.

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

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

For a tool with no output schema, the description thoroughly explains the return shape and refusal behavior, which is exactly what an agent needs. It also covers routing behavior, when to prefer it, and the cost tradeoff, making the entire call contract self-sufficient.

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

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

The schema already provides 100% coverage of the parameters, including the natural-language question and its five aliases. The description does not add parameter-level detail, but given the aliases make all parameters equivalent, no extra parameter semantics are truly necessary. It earns the high-coverage baseline.

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

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

The description clearly identifies the tool as a hallucination-resistant, grounded answer mode and separates it from its sibling ask_pipeworx by explaining that it extracts answers using only tool-result content. It names the exact high-stakes use case and explicitly contrasts itself with the casual-lookup sibling.

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

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

The description gives explicit when-to-use guidance — quoted, cited, or acted-on answers where inventing facts is unacceptable — and when not to use it: casual lookups, for which ask_pipeworx is preferred. It also discloses the cost tradeoff of one extra LLM call, giving the agent clear, actionable routing criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, lowering the bar, but the description adds extensive behavioral context beyond these. It discloses safety mechanisms (low-confidence resolution suppresses analysis fields, closed markets return blocking status), wide-spread tradeability notes, cancellation-rule parsing with ev_impact quantification, and news fallback behaviors. No contradiction with annotations.

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

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

The description is long but well-structured with uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) that aid scanning. The first sentence front-loads the core purpose, and every section adds critical operational information for a complex tool. While dense, it earns its length; a 5 would require even tighter prose.

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

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

Given there is no output schema, the description thoroughly explains return shapes (market, analysis, evidence), resolver contract, parent-event extractor, news fields, and safety routes. It covers edge cases like low-confidence matches, closed markets, wide spreads, and cancellation rules. This is a complete operational picture for an agent to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some context for the market parameter (slug, URL, or question text), but this duplicates what the schema already states. It does not add meaningful semantics for depth or include_raw beyond what the schema provides. The description's value lies more in explaining tool behavior than in clarifying parameter meanings.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from siblings like polymarket_arbitrage or polymarket_edges by focusing on a single bet and its evidence packet. It also provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), 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?

The description explicitly lists when to use the tool ('Use for...') and gives detailed fan-out examples by bet type, which implies appropriate contexts. However, it does not explicitly state when not to use it or name alternative sibling tools, so it stops short of a 5. The clear context and examples still provide strong 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 the annotations by detailing exact data sources (SEC EDGAR/XBRL, FAERS), specific metrics (revenue, net income, cash, long-term debt, adverse-event counts, FDA approval counts, trial counts), handling of off-calendar fiscal years, sorting behavior by primary metric, and output format with citation URIs. This is rich behavioral context.

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

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

The description is dense but every sentence carries useful information. It opens with trigger phrases, then states the preemptive usage preference, followed by data source specifics, sorting behavior, and output details. No filler or redundancy.

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

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

For a tool with two parameters and no output schema, the description covers all essential aspects: input constraints (2–5 entities), entity types, data sources, sort order, output format (paired data + citation URIs), and performance benefit. It is fully self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100% but the description adds meaning beyond the schema by explaining what each 'type' value retrieves (company financials vs drug trial/adverse-event data) and gives concrete examples like 'AAPL', 'MSFT', 'ozempic', 'mounjaro'. It also clarifies result sorting, which helps agents understand parameter implications.

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 comparison of 2–5 companies or drugs in one parallel call, with explicit trigger phrases like 'Compare X and Y' and 'X vs Y'. It also distinguishes itself from siblings by contrasting with 'sequential single-pack lookups' and stating it 'Replaces 8–15 sequential lookups'.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a strong usage directive. It also lists specific query types that should invoke this tool and implies a limit of 2–5 entities, giving clear context for 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?

Thoroughly discloses behavior beyond the annotations: parallel facet decomposition, gap recovery, contradiction scanning, hop fields, citation_uri fetchability guarantees, semantic excerpting, and expected latency. No contradiction with the readOnly/idempotent hints.

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

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

The content is highly informative but quite verbose, repetitive, and formatted in long ALL-CAPS blocks that reduce skimmability. Key caveats are front-loaded, but the description could be tightened without losing meaning.

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

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

Though there is no output schema, the description thoroughly explains the shape of the returned findings packet, including evidence, confidence, source, fetched_at, hop, contradictions, and gaps. Lacks only a formal output schema, but the prose is complete enough for an agent to know 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 covers both parameters and the enum, and the description augments this with meaningful detail about question decomposition and depth behavior. Could be slightly more concise, but the added semantics are valuable and not redundant.

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

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

Clearly states this is a grounded multi-source research tool over 1517 structured data sources, decomposing broad questions and returning a findings packet. Explicitly differentiates itself from ask_pipeworx and live-news tools in the sibling set.

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?

Gives explicit when-to-use guidance: broad/multi-part structured-data questions; direct for single lookups, breaking news, and colloquial current-world topics to use ask_pipeworx instead. Also explains depth-level trade-offs and paid tier requirements.

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?

While annotations already declare readOnly, idempotent, and non-destructive behavior, the description adds valuable behavioral context: it returns top-N relevant results with full schemas and examples, ready to call without a second lookup. This goes beyond the annotations and informs the agent about the tool's meta nature and output completeness.

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

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

The description is concise and well-structured: purpose first, then when-to-use, then return details. Every sentence earns its place, with no filler or repetition of schema content. It is appropriately sized for the tool's complexity.

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

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

Given the tool's purpose (discovery of other tools) and absence of an output schema, the description sufficiently explains the return payload (names, descriptions, full schemas) and the use case. It also lists the major domains covered, making it complete for an agent deciding 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%, and the description does not add parameter-level insight beyond what the schema already provides. The baseline for high schema coverage is 3, and this description meets it without elevating the parameter understanding.

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

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

The description opens with a specific verb+resource ('Find tools by describing the data or task') and clarifies its scope by listing many supported domains. It clearly distinguishes itself from sibling research tools by positioning itself as a meta-tool to discover other tools, reinforced by the directive to call it FIRST.

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

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

The description explicitly states when to use ('Use when you need to browse, search, look up, or discover what tools exist') and provides strong context ('Call this FIRST when you have many tools available and want to see the option set, not just one answer'). This implies the alternative—directly invoking a known tool—and sets clear expectations.

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

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

Annotations already mark readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: parallel fan-out across multiple sources, soft-fail for USPTO sunset, empty sections meaning real 'no data', name resolution via SEC EDGAR, and the type parameter accepting both values. This goes well beyond annotations and helps set expectations for the agent.

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

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

Long, but every sentence earns its place: launch examples, primary purpose, source fan-out list, detailed return-field breakdown, and parameter clarifications. The most critical 'use this over chaining' message is front-loaded, and the structured enumeration of return fields keeps the length justifiable.

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

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

With no output schema, the description must convey return shape, and it does thoroughly: cik, company_name, recent_filings with URIs, fundamentals fields sorted by period, patents, federal_contracts, fda_products with nuance about small-molecule drugs, hiring, news, LEI, and sources_used/failed. Edge cases (private companies, empty sections, soft-fail) are also covered, so an agent has everything needed to invoke and interpret results.

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

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

Schema coverage is 100% and the description reinforces and extends the schema. It restates that `value` can be a ticker, zero-padded CIK, or company name, adds that names resolve via SEC EDGAR company-name match, and clarifies that `type` accepts 'company' or 'ticker' interchangeably. The examples (AAPL, 0000320193, Moderna) make parameter usage unambiguous.

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

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

Description opens with concrete user phrasings ("Tell me about X", "company profile for Microsoft") and a crisp statement: "full cross-source profile of a US public company in ONE parallel call." It then differentiates from siblings by explicitly preferring this over chaining single-pack SEC/XBRL/news lookups when a holistic view is wanted.

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?

Gives explicit when-to-use guidance: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also defines boundaries, e.g., private companies return resolved:false with a note rather than a bare failure. This tells the agent both when to invoke and what to expect in edge cases.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the core behavioral traits are covered. The description adds little beyond saying 'delete,' which is redundant with the destructive hint. It does mention 'previously stored memory' and 'clear sensitive data,' but these are more usage-oriented than new behavioral disclosures.

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, consisting of two sentences. The first sentence states the core function, and the second provides usage guidance and related tools. Every sentence is useful, with no fluff or repetition.

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

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

For a simple one-parameter delete tool, the description combined with annotations covers all necessary context: purpose, when to use, related tools, and safety profile. No output schema is needed for explaining return values, and the tool's behavior is fully disclosed through the description and annotations.

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

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

The schema has 100% coverage for the single parameter 'key' with description 'Memory key to delete.' The tool description does not add any additional meaning or constraints beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action: 'Delete a previously stored memory by key.' This is a specific verb+resource combination that distinguishes it from siblings like remember and recall, which store and retrieve memories respectively.

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

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

The description provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names related tools ('Pair with remember and recall'), giving clear context on how this tool fits into the overall workflow.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds process transparency by detailing that it fetches the page, extracts metadata, and emits a standard format text blob. This gives the agent expectations about input handling and output without contradicting annotations. It doesn't address failure modes, but the safety profile is already covered.

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

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

The description is three sentences, front-loaded with the core purpose, followed by process and use cases. Every sentence adds value; there is no filler or redundancy. Well-structured and easy to parse.

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

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

The description covers purpose, process, output format, and use cases. With only two parameters and no output schema, this is sufficient for an agent to understand the tool. However, it could have mentioned behavior on inaccessible URLs or rate limits, but these are minor gaps. Overall complete for the tool's simplicity.

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

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

The input schema already describes both parameters (url and max_links) with 100% coverage. The description does not add additional parameter details beyond what schema provides, such as format constraints or defaults. Since schema coverage is high, 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 function with a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It explains the process (fetch, extract, emit) and distinguishes itself from siblings by focusing on file generation for AI crawler indexing. The title and name are expanded, not tautological.

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 use cases with 'Useful for:' covering client work, personal projects, and competitive auditing. It does not explicitly exclude alternatives or name sibling tools, but the context is sufficient for an agent to decide when to use this tool. Missing explicit when-not-to-use guidance prevents a 5.

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

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

Annotations already indicate read-only/idempotent/non-destructive. The description adds useful behavioral context: returns specific fields, defaults to active subscriptions, and is scoped to the caller. 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?

Two sentences that efficiently pack the action, return fields, and use cases. No redundancy or filler.

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

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

For a simple listing tool with one optional param, the description explains the return value and when to use it. The annotations cover safety, making it complete.

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

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

Schema description coverage is 100% and the include_inactive parameter has a clear description. The tool description adds no additional parameter semantics, so baseline 3 is appropriate.

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

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

The description uses a specific verb 'List' with resource 'the caller's active subscriptions', clearly distinguishing it from subscribe/unsubscribe siblings. The scope (caller-specific) and return fields are explicitly stated.

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 it: 'review what you're monitoring before adding more or to find an id to cancel.' It lacks explicit when-not or named alternatives, but the context is clear enough.

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, so the description carries the full burden of behavioral disclosure. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token workflow (returns a token, can be reused to read resolution status), and that it is free and does not count against tool-call quota. This goes well beyond what annotations provide.

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

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

The description is long but every sentence delivers necessary guidance: purpose, use cases, exclusion, message content, token mechanics, and rate limits. It is front-loaded with the core action and follows a logical flow. Slightly verbose, but not wasteful.

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 the main return behavior (claim_token) and how to follow up. It also covers the four parameters, the exclusion rule, and operational constraints. It does not describe the immediate success response for non-claim_token submissions, but the token path is sufficiently specified.

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 meaningful guidance beyond field names: it instructs users to describe issues in terms of Pipeworx tools/packs and not to paste end-user prompts, and explains the claim_token usage ('pass it back later... with no other arguments'). This elevates it above baseline.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback types (bug, feature, data_gap, praise) and differentiates itself from sibling tools by being the only feedback channel, while also noting what it is not for (other MCP servers).

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 (wrong/stale data, missing catalog entries, praise) and an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It even offers a disambiguation heuristic ('Pipeworx tool names are the ones this connection lists'). This is exemplary.

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

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

Annotations already declare read-only, idempotent, and open-world traits. The description adds beyond this: it discloses the data source (CF analytics-engine), the no-PII guarantee, the output tuple shape, and a 5min–1h cache window, giving the agent useful context about staleness and provenance.

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, each earning its place: purpose, use cases, data provenance/PII, and caching. Slightly longer than an ideal two-sentence description, but there is no filler or redundancy—it is front-loaded and well-structured.

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

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

For a simple tool with one optional parameter and no output schema, the description is fully sufficient. It describes return contents, windows, use cases, and freshness behavior. The agent can confidently decide when and how to invoke it without further clarification.

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

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

The schema covers the single 'window' parameter 100%, including enum values and semantic explanation (shorter vs. longer windows). The description repeats the valid values but adds no new parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

Description clearly identifies the tool as returning trending usage data for Pipeworx (top tools, packs, and total call volume) across a configurable time window. This is specific and distinguishes it from sibling tools like discover_tools (static list) or recent_alerts/recent_changes (event-driven).

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 three explicit use cases (hot data sources, canonical tool confirmation, agent alignment check) that give clear context for when to call. It does not name alternative tools for when-not scenarios, but the guidance is concrete 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?

Beyond the readOnly/idempotent annotations, the description discloses key thresholds and behaviors: 'deviations >3pp emit a BUY/SELL EVERY LEG signal', the semantic anchor '≥0.30 Jaccard similarity', the partition filter with '>20% placeholder fraction return null arb signal', and the fill check rule 'realizable_edge_pp ≤ 0 means... do not trade it.' This is rich and goes well beyond annotations.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and stays on-topic. Every sentence adds necessary detail for a complex tool, though it could be trimmed slightly without losing meaning.

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

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

There is no output schema, but the description explicitly outlines the response fields: 'opportunities[] (gap_pp, suggested_trade, reasoning...)', 'partition_check{sum_yes_prices, gap_from_1...}', and fill-check outputs. Combined with parameter examples and safety caveats, this fully equips an agent to call the tool correctly.

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

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

The schema already covers both parameters with descriptions, and the tool description adds usage context: examples of event slugs ('fed-decision-may-2026'), topic seeds ('Strait of Hormuz traffic returns to normal'), and what each mode returns. This gives the agent both syntax and semantics.

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

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

The description opens with a specific verb and scope: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (no args, event, topic) and explains what each does, setting it apart from siblings with its focus on arbitrage detection.

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

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

It explicitly states when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...' and recommends event for a specific market. It also points users to a sibling tool: 'For custom sizing use polymarket_fill_risk.' This is explicit when/when-not guidance.

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

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

The description provides extensive behavioral context beyond the annotations, such as caching ('Cached 1h at the KV level keyed on all knobs'), response structure (by_segment, fed_candidates, _diagnostics), and warnings about 24h moves. It also explains why certain segments are excluded and how knobs affect filtering. This significantly exceeds the baseline set by the readOnlyHint and idempotentHint 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 (model families, response top-level, knobs) and front-loaded with the core purpose. However, it is excessively long and dense, containing many implementation details (e.g., specific alpha values, 90d FRED log-returns) that may be unnecessary for selecting the tool. While every sentence is relevant, the overall length and detail reduce conciseness.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is exceptionally thorough. It explains the response structure, diagnostics, caching, exclusions (e.g., Fed bets), and how knobs affect behavior. This is more than sufficient for an agent to understand what the tool returns and how to use it effectively, even without an output schema.

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

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

The schema descriptions already cover all 9 parameters at 100% coverage, so the schema does the heavy lifting. The description adds some narrative around tradeable-edge knobs (e.g., min_liquidity, max_spread_pp) but mostly restates what the schema already explains. It does not add substantial new meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', with a specific verb, resource, and scope. It distinguishes its purpose from sibling tools implicitly through its unique focus on model families and edge detection, but it does not explicitly name alternatives, so it lacks the explicit sibling differentiation required for a 5.

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

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

The description gives clear context for when to use the tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It implies the use case but does not provide explicit when-not-to-use instructions or name alternative tools, so it falls short of a 5.

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

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

The description goes far beyond the annotations by disclosing operational details: snapshot gaps mean no scan occurred, history depth bounded by a 60-day TTL, decay computed from daily closes (not intraday). These are critical behavioral nuances that annotations alone cannot convey, and there is no contradiction.

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

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

The description is longer but extremely well-structured with clear labels (RESPONSE:, LIMITS:). It front-loads the essential purpose and then details output and limitations. Every sentence delivers useful information; the length is justified by the tool's complexity.

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

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

With no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and the meaning of each field, including derived metrics like decay_pp_per_day. It also covers important caveats (TTL, data gaps), making the tool's behavior fully understandable.

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 context by explaining 'window' as a 'snapshot family' and clearly states defaults (14 days, '1wk'), which clarifies the conceptual role of the parameters beyond the schema's field-level descriptions.

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

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

The description clearly states the tool's function: edge persistence and decay telemetry built from daily polymarket_edges snapshots. It uses a specific verb ('Answers') and defines the resource (edge history), distinguishing it from sibling tools like polymarket_edges which likely computes 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?

The description provides clear context for when to use the tool: when you need to know how long an edge has existed and whether it is shrinking, as exemplified by comparing a fresh vs. stale edge. It does not explicitly name alternatives/exclusions, but the use case is well-conveyed.

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

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

Even with annotations declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds rich behavioral context: it 'walks the ladder,' returns detailed fields like top_of_book, vwap_fill_price, and a verdict (clean|degraded|cannot_fill), and warns about forced_directional_risk and thin_legs. It also discloses that partial basket fills convert arb into an unhedged directional position, which is critical behavioral information 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 dense and information-rich, front-loaded with the core purpose and structured via 'SINGLE-MARKET:' and 'BASKET:' labels. However, it is a long wall of text that repeats some schema details (e.g., default 1000, parameter modes) and enumerates many return fields that might be better in an output schema. It earns high marks for usefulness but loses a point for being somewhat verbose and borderline run-on.

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

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

For a complex tool with two modes, four parameters, no output schema, and a rich set of return values, the description is exceptionally complete. It covers all required inputs, explains default behaviors, lists comprehensive outputs including edge cases (thin_legs, max_clean_notional_usd, forced_directional_risk), and ties the tool into the broader arbitrage workflow. The annotations cover safety, and the description covers semantics, leaving no obvious gaps.

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

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

Schema coverage is 100% with detailed descriptions for all four parameters, so the baseline is 3. The description adds meaningful nuance: 'side' in basket mode is explained as 'sell_yes = capture overround by selling every leg, buy_yes = capture underround,' and size_usd is clarified as 'max spend on buys, target proceeds on sells.' This goes beyond the schema's basic 'USD to spend' and aids parameter selection.

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

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

The description opens with a specific, action-oriented purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by framing this as the pre-trade risk validation step, and it details two distinct modes (single-market and basket) with unique 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 explicitly states when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the reasoning—theoretical overround is not capturable on thin books and partial fills create unhedged directional risk—providing clear context for when this tool is necessary versus alternatives.

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

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

Annotations already signal read-only, idempotent, non-destructive behavior, but the description goes far beyond that. It explains that pairings are keyword-based and therefore 'pairing_unverified', lists every compatibility code with meaning, discloses the fee treatment (gross spread, no Kalshi fee model), notes when legs are skipped and why, and clarifies that `temporal_alignment_unknown` is not the same as confirmed alignment. This is exceptionally transparent and leaves little hidden about the tool's behavior.

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

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

The description is a dense wall of text, over 300 words, with uppercase section headers but no line breaks. It repeats concepts, e.g., `temporal_alignment_unknown` is described twice, and `pairing_unverified` is explained in two places. While structured by topic (modes, response, safety fields), the redundancy and lack of formatting make it harder to scan. The length is partially justified by the absence of an output schema, but it exceeds what concise writing would require.

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

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

With no output schema, the description must document return structure, and it does so thoroughly: leg prices, `spread[].top_spreads_pp`, `compatibility_warning`, `compatibility_codes[]`, per-spread `flags[]`, `skipped_unclassified`, `low_confidence_pairs[]`, `temporal_alignment`, and `fees_note`. It also explains counter semantics and the meaning of null values. The agent has everything needed to interpret the response and call the tool correctly.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description adds value by enumerating the 10 pre-mapped `topic` values and explaining the override relationship between `topic` and the explicit ticker/slug parameters. This clarifies how the two modes interact and what happens when both are provided, which the schema alone does not convey.

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?

Opens with a specific, unambiguous statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies the resource, the operation, and the unique value relative to other polymarket-only siblings. The rest of the description reinforces the purpose by detailing modes and output, leaving no doubt about what the tool computes.

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 lays out two invocation modes (`topic` and explicit ticker/slug pairing) and explains when each is appropriate. It adds an important caution that pre-mapped topics often return compatibility warnings, helping the agent set expectations. However, it does not compare with sibling tools such as `polymarket_arbitrage` or `polymarket_edges`, so the agent must still infer when those are better choices.

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, destructiveHint, and idempotentHint, but the description adds valuable context about scoping (anonymous IP, BYO key hash, account ID) and the listing behavior. This goes beyond structured data without contradicting it. The description could mention return format details, but the existing annotations lower the burden.

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

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

Three sentences, front-loaded with the core action, and every sentence earns its place. It efficiently covers purpose, usage context, and related tools without redundancy or filler.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers what it does, when to use it, how scoping works, and how it relates to sibling tools. No gaps remain for the agent to invoke it correctly.

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

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

Schema covers 100% of the single parameter (key), so baseline is 3. The description adds practical examples of what keys might contain (target ticker, address, research notes) and explicitly clarifies the omit-to-list behavior, enriching beyond the schema's simple string description.

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

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

The description clearly states the tool's function with specific verbs: 'Retrieve a value previously saved via remember, or list all saved keys'. It distinguishes itself from siblings by referencing remember (save) and forget (delete), making its role as the retrieval component evident.

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

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

Provides explicit usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names companions (remember, forget) and clarifies the optional key argument behavior, offering clear when-to-use guidance versus re-deriving information.

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 that mark_read:true flags returned events as read, mutating persisted state, which directly contradicts the readOnlyHint=true annotation. It also undermines idempotentHint because repeated calls with same parameters can yield different results when mark_read is used.

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-load the purpose and add only high-value details: payload contents, filtering, mark_read behavior, and an alternative endpoint. No redundant content.

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

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

The description covers return payload, filtering, mark_read, and even the alternative URL, while the schema documents all parameters. It lacks explicit mention of unread_only behavior in the description, but schema covers it. The contradiction with annotations slightly clouds overall completeness but does not affect description completeness.

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

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

With 100% schema coverage, the baseline is 3, but the description adds an example type ('sec_8k'), clarifies the since parameter as an ISO timestamp, and explains the downstream effect of mark_read on subsequent calls, providing meaningful extra 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 the tool pulls fired events from the subscription feed, with specific details about payload fields and filtering options. However, it does not explicitly differentiate from sibling tools like recent_changes or list_subscriptions, so it falls short of full distinction.

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

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

The description implies usage via polling and offers an alternative external URL for scripts/dashboards, but does not specify when to use this tool versus sibling MCP tools. No exclusions or direct alternative tool names are given.

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 details fan-out behavior across SEC EDGAR, GDELT→GNews fallback with conditions, USPTO soft-fail due to PatentsView API sunset, and the exact return format (changes[], total_changes, citation URIs). This is rich behavioral context not available from annotations alone.

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

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

The description is a dense paragraph but well-organized, front-loaded with usage examples. Each clause adds value (sources, fallbacks, return structure, alternative). Slightly long but justified by the tool's multi-source complexity.

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

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

With no output schema, the description compensates by stating the return shape ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also covers source limitations, partial failure modes, and parameter semantics, making it self-sufficient for an agent to invoke correctly.

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

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

The schema already covers all three parameters with 100% description coverage, including `since` formats and `value` examples. The description adds no meaningful parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' with specific examples like 'What's new with X'. It distinguishes itself from sibling entity_profile by explicitly naming it as the alternative for static profiles.

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

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

The description gives explicit guidance on when to use this tool versus entity_profile: 'Use entity_profile instead when you want the static profile...'. It also shows natural-language query triggers and mentions it operates in 'ONE parallel call', implying efficiency for batch change 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 provide idempotentHint=true and destructiveHint=false. The description adds behavioral context beyond annotations: storage as a key-value pair scoped by identifier, persistence differences for authenticated vs. anonymous sessions (24-hour retention). This clarifies important runtime behavior 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?

Each sentence earns its place: purpose, usage scenario, storage model, retention policy, and related tools. It is front-loaded with the primary action and remains concise despite covering multiple dimensions. No fluff or repetition of schema content.

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

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

For a simple 2-parameter write tool with no output schema, the description is fully adequate. It explains persistence, scoping, retention, and sibling relationships, covering all relevant context. No critical gaps remain for an agent to invoke it correctly.

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

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

Schema already covers both parameters (key, value) with descriptions and examples (100% coverage). The description adds semantic value by explaining what kind of data is worth storing ('a resolved ticker, a target address, a user preference') and the key-value scoping, helping the agent choose appropriate parameter values beyond simple syntax.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes from siblings by naming recall and forget as complementary actions. The scope (across conversation or sessions) is explicitly stated.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. It also names alternatives: 'Pair with recall to retrieve later, forget to delete.' This gives unambiguous direction on when to invoke this tool vs. its 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 already indicate a safe, read-only, idempotent operation, and the description adds substantial behavioral context beyond that: graceful degradation when LEI/FIGI sources are unavailable, the cascading internal lookups, explicit unresolved identifiers, ambiguous match handling via figi_candidates, and source labeling for every identifier.

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

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

The description is dense and front-loaded with the core purpose and usage rule, and every section adds operational value. It is longer than many tool descriptions, but given the breadth of entity types, fallback behavior, and identifier semantics, the length is justified rather than redundant.

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

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

Despite having no output schema, the description sufficiently covers what the agent needs to call the tool correctly: input formats, entity types, resolution sources, ambiguity behavior, unresolved identifier handling, failure tolerance, and the multi-lookup nature. It even educates the agent on non-equity instruments and issuer-name edge cases.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantic guidance beyond the schema: example values, the warning to pass only the entity name and never the full noun phrase, and the rationale that FIGI lookup matches instrument names — all of which help prevent common invocation mistakes.

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

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

The description states a specific verb and resource: resolving a user-spoken NAME to canonical/official identifiers. It explicitly distinguishes the tool's role ('other tools require as input', 'Use FIRST whenever you have a name but need an ID') and enumerates supported entity types, making its purpose clear even among many 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 gives strong when-to-use guidance with concrete user-phrase examples and the directive 'Use FIRST whenever you have a name but need an ID.' It does not explicitly name alternatives or when-not-to-use conditions, so it stops short of full exclusionary guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by explaining the probe-and-rank process and the output summary (score, confidence, signal density). It does not restate annotations but adds behavioral detail about how entities are processed and compared.

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

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

Three sentences front-load the core purpose, then explain the mechanism and use case. No wasted words; every sentence conveys distinct information (purpose, process/output, example scenario).

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 (4 params, no output schema) and rich annotations, the description adequately covers what it does, how it works, and what it returns (ranked list with score/confidence/signal density). It could mention entity count limits or execution time, but these are already in the schema param descriptions, so not a major gap.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). The description adds important extra semantics for the 'entities' parameter: 'First entry treated as the "subject" for narrative; rest are competitors.' This goes beyond the schema's description and clarifies ordering behavior.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), and clearly distinguishes from siblings by emphasizing side-by-side comparison and ranking. It explicitly mentions probing with ai_visibility_check and ranking by score, which uniquely identifies this tool's functionality.

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

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

Provides clear context: 'Useful for competitive AI-marketing audits' and gives a concrete example prompt. It implies the difference from ai_visibility_check (single entity vs multiple) but does not explicitly state when-not-to-use or name alternative tools for single-entity checks.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds valuable behavioral context beyond those: fanned-out calls to multiple external services, graceful degradation on partial failures, bundlephobia's first-measurement delay of 5-30s, and the presence of a sources_failed field. 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 a single dense paragraph but logically structured: composite purpose, data sources, usage trigger, return fields, ecosystem limitation, and error behavior. Every sentence contributes useful information, though it is longer than strictly necessary. It earns a 4 rather than 5 due to 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?

This is a complex external-data-fan-out tool with no output schema, so the description must explain return values and edge cases. It does so thoroughly: lists all summary fields, per-advisory detail, links, alternative versions, mentions sources_failed, and explains ecosystem boundaries and timeout behavior. No gaps.

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

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

Input schema coverage is 100%, with both 'package' and 'version' already described. The description mentions scoped packages and default-to-latest, which are also in the schema, so it adds no new parameter-level semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs a composite 'should I add this npm package to my project' check, listing specific data sources (deps.dev, bundlephobia) and output fields. The verb 'scan' plus resource 'dependency' is specific, and it distinguishes itself from siblings by being npm-specific and composite.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This tells the agent when not to use it and what to use instead.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, lowering the bar. The description adds context by naming the external source (Pixabay) and the nature of returned data (URLs, tags, likes, download counts), which is useful for the agent. It does not mention API key requirements, but the openWorldHint annotation flags external access.

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

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

The description is a single, front-loaded sentence with no fluff. It packs the action, resource, key filters, and return types into about 25 words, earning its place with useful information.

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

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

With a well-documented 12-parameter schema, an existing output schema, and clear annotations, the description is adequately complemented by structured metadata. It adds necessary orientation for selecting the tool and mentions return payload components. The only minor gap is the lack of explicit note on API key usage, but the schema examples contain '_apiKey'.

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% description coverage for all 12 parameters, so the baseline is 3. The description's enumeration of filter dimensions (keyword, image_type, category, orientation, colors, order) is a redundant high-level summary, not adding new meaning beyond what the schema already specifies.

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 the specific resource (Pixabay's library of royalty-free photos and illustrations), and differentiates the tool from siblings like search_videos by naming its content type and search dimensions. It lists filterable attributes and return fields, making the tool's scope unmistakable.

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

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

The description gives clear context for when to use the tool (searching images on Pixabay) but does not explicitly mention alternatives or exclusion cases. The differentiation from search_videos is implied by the resource and content type, but not spelled out as a recommendation.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the description need not repeat those. It adds useful context about the output (stream URLs at multiple resolutions, tags, view counts) and the royalty-free nature of the videos, but does not disclose behavioral details like pagination mechanics or rate limits. With annotations present, this is adequate but not exceptional.

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

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

The description is a single, front-loaded sentence. It conveys the purpose, scope, and output without any filler or repetition of schema content. Every phrase 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?

Given the 7 parameters are fully described in the schema, an output schema exists, and annotations cover safety and world semantics, the description provides enough context for an agent to select and invoke the tool correctly. It clearly communicates the resource and return format without needing to restate structured 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%, so parameters are fully documented in the schema. The description adds a brief summary of the main filter dimensions (keyword, video_type, category, order), which mirrors the schema but helps prioritize. This meets the baseline for high schema coverage; it does not significantly enrich 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 it searches Pixabay's royalty-free videos with specific filter dimensions (keyword, video_type, category, order) and enumerates the return type (video stream URLs at multiple resolutions, tags, view counts). This goes beyond a generic 'search videos' and distinguishes it from sibling search_images by focusing on videos and their specific output.

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

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

The description implies usage for video search but provides no explicit guidance on when to use this tool versus alternatives like search_images. It does not mention exclusions or provide examples of when to prefer another tool. The context is clear but not elaborated, so it meets the 'implied usage' level.

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 readOnly, idempotent, and non-destructive behavior, and the description adds substantial non-obvious details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char truncation with a flag, and character offsets for verification. These go well beyond the structured annotations and help the agent anticipate tool behavior.

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

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

The description is compact yet information-dense, with every sentence contributing to purpose, usage, pairing, or mechanics. It is front-loaded with the core action and keeps related details together, making it easy to scan.

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

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

With no output schema, the description adequately describes return values ('passages with character offsets and similarity scores') and edge behavior (truncation flag for inputs over 200K chars). It provides enough context for an agent to decide when and how to invoke the tool without additional ambiguity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context: concrete examples for text ('a SEC 10-K body, an article, a long tool result') and query ('supply-chain risk', 'fiscal year 2024 revenue'), and clarifies that the output is passages with offsets and similarity scores. This exceeds what the schema alone provides, though not dramatically.

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

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

The description uses a specific verb ('search inside') and resource ('fetched record'), clearly distinguishing this semantic-search-over-provided-text tool from sibling tools like search_images or ask_pipeworx. It immediately states the input (pulled text + natural-language query) and the output (top-N passages with offsets and scores).

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

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

It explicitly states when to use this tool ('when the record is too big to cram into the prompt') and explains the benefit (saves context, returns only relevant passages). It also names a companion workflow with ask_pipeworx_grounded, saying to ground over relevant passages instead of the whole document, which provides 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, openWorldHint=true), the description discloses important behaviors: requires OAuth, feed is always-on, SMS phone verification and 10/day cap, and returns the new subscription id. It does not contradict annotations and adds valuable context about side effects and constraints.

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 the main purpose, but it is somewhat lengthy, repeating details that are also in the schema (delivery channels, params examples). Each sentence earns its place, though a tighter version could rely more on the schema for parameter specifics. Still, it is structured and scannable.

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

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

The tool has moderate complexity with nested objects and no output schema, and the description covers core aspects well. However, it omits two of the five supported types (patent_grant and clinical_trial) even though they are in the schema, which could mislead an agent into thinking they are unsupported. It also lacks some failure/edge behavior details, though the schema fills many gaps. A complete description should at least mention all types.

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 parameters with detailed descriptions (100% coverage), so baseline is 3. The description adds value by providing real-world examples and explaining abbreviations (e.g., items:["5.02"] = officer change) for some types, though it omits patent_grant and clinical_trial, which are present in the schema but not the description. The extra examples elevate it slightly above baseline.

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

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

The description opens with a clear, specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also states the return value (new subscription id) and differentiates from sibling tools like list_subscriptions or unsubscribe by focusing on subscription creation. The supported types are enumerated, making the tool's scope unmistakable.

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

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

The description provides strong context for when to use this tool: when a persistent, proactive subscription is needed, and it notes authentication requirements (Pipeworx OAuth account, anonymous/BYO cannot persist). It does not explicitly name alternatives or when-not-to-use, but the context is clear enough for an agent to select this over one-off lookup tools like recent_alerts.

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 readOnly/openWorld/idempotent hints. The description adds valuable behavioral detail: it returns category-bucketed example questions with the exact tool+argument shape, draws from a live catalog, and supports both no-arg and topic-focused invocation. No contradiction with annotations.

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

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

The description is front-loaded with user queries and uses dashes to clearly separate return, invocation, and usage details. It's longer than minimal but every sentence earns its place; only a slight redundancy with the title prevents a 5.

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

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

Despite having no output schema, the description fully explains what is returned (category-bucketed examples with tool+argument shapes), how to invoke (no args or topic), and when to use it first. It also covers the topic options and alternative tools, making it complete for an onboarding 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 the schema description already lists all allowed topic values and the omit-for-full-spread behavior. The description only repeats examples like 'finance' and 'betting', adding no new meaning. 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 is crystal clear: it lists concrete user prompts ('What can I ask Pipeworx? / what is Pipeworx good for?') and labels the tool as 'the onboarding entry point'. It also distinguishes from sibling tools by naming meta-tools (ask_pipeworx, entity_profile, compare_entities) and stating this should be used FIRST to learn them.

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

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

Explicitly tells the agent when to use this tool ('Use this FIRST when you do not yet know what Pipeworx can do for you') and when to learn meta-tools instead. It names concrete alternatives and gives a clear ordering, which exceeds the 'clear context' bar.

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

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

Goes beyond annotations by disclosing that the row is deactivated, not deleted, and historical events remain available via recent_alerts. Also explicitly mentions ownership enforcement, adding behavior context that annotations don't cover.

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

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

Two concise sentences, front-loaded with the primary action, and no filler words. Every clause provides valuable 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 one-parameter tool with no output schema, the description covers the action, ownership constraint, and side effects sufficiently. The reference to recent_alerts ties it to related context.

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

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

Schema coverage is 100% with the id parameter well described as a UUID returned by subscribe. The description doesn't add significant extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the action 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from siblings like subscribe and list_subscriptions by focusing on cancellation.

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

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

Provides clear context: ownership is enforced and only own subscriptions can be canceled. It explains the effect on recent_alerts, helping the agent decide when to use this tool, though it doesn't explicitly name 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 annotations (readOnlyHint, openWorldHint, idempotentHint) are reinforced and expanded by the description. It discloses critical behavioral nuances: the distinction between can't-verify (could_not_verify with verification_error) and unsupported (no source found), the structured vs. grounded routing, and the return of citations. This goes well beyond the annotations and prevents misinterpretation of the 'could_not_verify' verdict.

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

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

The description is dense but well-organized, front-loading trigger phrases and key purpose, then systematically detailing pipeline variants, verdict values, and critical caveats. Every sentence contributes useful information, though the length is somewhat high for a simple read-only tool. It earns a 4 for being efficient and 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?

With no output schema, the description carries full responsibility for explaining return values. It lists all possible verdicts, mentions the actual value with citation, reasoning, and the special error field. It also explains the two processing paths and the meaning of unsupported. This is complete enough for an agent to understand what the tool will return and how to interpret it.

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

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

Schema coverage is 100% for both parameters, so the schema already fully documents claim and tolerance_pct. The description adds some context about the natural-language nature of the claim and tolerance behavior, but this largely echoes the schema. It does not provide significant additional meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with explicit trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states the core function: natural-language claim verification against authoritative sources. It clearly distinguishes this tool from siblings by centering on fact-checking, and the first sentence names the resource (authoritative sources) and action (verify).

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also outlines two distinct pathways (SEC EDGAR fast path vs. grounded pipeline) and notes it replaces 4–6 sequential calls. However, it does not explicitly name alternative tools or state when not to use it, so it falls just short of a 5.

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