Opencitations

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that passing an _apiKey triggers external calls to Anthropic, with the user paying directly. This is a meaningful behavioral and cost disclosure. It could add more details about rate limits or data handling, but the added context justifies above-baseline scoring.

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

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

The description is four sentences and front-loaded with the core purpose. Each sentence earns its place: purpose, model options, return format, and use cases. It is slightly longer than strictly necessary, but every added detail is useful and there is no fluff.

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

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

For a tool with no output schema, the description adequately explains the return structure (per-model object with score, confidence, signals, raw_response, plus a combined view). It also covers model selection, cost, and use cases. It could mention error or edge cases, but overall it is complete enough 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 already 100%, which sets a baseline of 3. The description adds value by explaining the default model choice, the meaning of _apiKey (BYO key and direct payment), and the purpose of the context parameter (disambiguation). This goes beyond the schema, nudging the score to 4.

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

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

The description clearly states the tool's function: it probes one or more LLMs for knowledge about an entity and scores visibility from 0-100 per model. The verb 'probe' and resource 'LLMs' are specific, and the outcome (visibility score) is unique. However, it does not explicitly distinguish this tool from siblings like scan_competitor_ai_presence, so it misses the top score.

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: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains model selection (default vs. Anthropic) and the cost implication. However, it does not mention exclusions or 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?

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds routing to thousands of tools, filling arguments, returning citations, and working on every tier, which goes beyond annotations. It doesn't mention rate limits or detailed error handling, but provides substantial context.

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

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

The description is long but information-dense, covering usage, differentiation, examples, and behavioral details in a structured way. There is some redundancy (e.g., 'PREFER OVER WEB SEARCH' repeated), but it remains scannable and each section earns its place.

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

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

For a complex router tool with no output schema, the description explains return format (structured answer with citations), escalation paths, and tier compatibility. It lacks details on ambiguity handling or error responses, but overall the essential context is well covered.

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 has 100% coverage with clear descriptions for question and its aliases. The description adds examples and trigger phrases, enriching the natural-language query guidance beyond the schema's bare definitions.

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

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

The description clearly states the tool's function: it routes factual questions to the right of 5,529 tools across 1,455 verified sources and returns structured answers with pipeworx:// citation URIs. It uses specific verbs and differentiates from siblings by naming 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?

Explicitly provides when-to-use and when-not-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and step-up instructions for ask_pipeworx_grounded and deep_research. Includes concrete trigger phrases and examples.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable experimental context: it is a working router that may have candidate routing improvements under test, currently no active candidate, and it 'falls back to nothing'—meaning it is fully functional. This goes beyond the annotations without contradiction.

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

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

The description is three sentences, front-loaded with the core identity ('Beta version of ask_pipeworx: identical universal router...'). Some redundancy exists ('Falls back to nothing' and 'full working router'), but overall every sentence contributes useful context.

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 as a beta universal router with no output schema, the description covers its current state, usage equivalence, and experimental nature. It also states 'same response shape' as ask_pipeworx, partially compensating for the lack of 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?

Schema coverage is 100% with all aliases described, so the baseline is 3. The description only reiterates 'same arguments' and directs users to ask_pipeworx, adding no new parameter-level meaning beyond the schema.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and same response shape. It explicitly differentiates from the stable ask_pipeworx by noting candidate routing improvements may be enabled, and it is currently equivalent to ask_pipeworx.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes results are compared against the stable router. It implies ask_pipeworx or ask_pipeworx_grounded as stable alternatives, but does not explicitly state when not to use this beta.

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

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

Beyond annotations, the description discloses refusal behavior (specific refusal_reason values), the fact that it extracts only from tool results, the return structure (evidence as verbatim quote, confidence, source), and the extra LLM call cost. No contradiction with readOnlyHint=true or idempotentHint=true.

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

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

The description is dense but well-structured, opening with a crisp summary, then explaining process, return format, usage, and cost in a logical order. Every sentence justifies its inclusion, with no filler.

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

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

Despite no output schema, the description fully specifies return values and refusal reasons. It also covers when to use, the relationship to sibling tools, and cost implications. This is a complete and self-contained explanation for a complex tool.

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

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

Schema coverage is 100% and the parameter is simply a natural language question with documented aliases. The description does not add meaning beyond the schema, but it does provide context about routing and extraction. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool is a hallucination-resistant answer mode for high-stakes reads, with a specific verb+resource and scope. It distinguishes from the sibling ask_pipeworx by explaining the grounded extraction behavior and additional LLM call cost.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and provides an alternative ('prefer ask_pipeworx for casual lookups'), along with the cost tradeoff. This is clear, actionable guidance.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description richly discloses behavior: fan-out parallelism, resolver contract with match confidence, suppression of fields on low confidence, closed-market handling, news fallback on 429s, and resolution-rule risk. It even quantifies the refund_50_50 scenario. This exceeds what annotations convey and provides critical safety context.

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

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

The description is long but well-structured with explicit sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT). It front-loads the core purpose and usage, then dives into details. Almost every sentence adds value, though it could be trimmed without losing essentials. The structure compensates for its size.

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?

Without an output schema, the description carries the full burden of explaining return values. It details response shapes (market, analysis, evidence), resolver fields, parent_event, news fallback fields, safety statuses, and resolution-rule risk. It even highlights the practical de-indexing behavior. For a complex tool, this is exemplary 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?

The schema covers 100% of parameters with clear descriptions, so baseline is 3. The description adds meaning by explaining how the market parameter is resolved (slug/URL/question text) and that fan-out is parallel. It also clarifies depth differences (quick vs thorough) via examples. Though some of this overlaps with schema, the resolver and response-shape details give extra context for interpreting parameters.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes this from sibling tools by focusing on market resolution, classification, and parallel data packs, with examples of input forms. This leaves no ambiguity about what the tool does.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives detailed fan-out examples and mentions blocking conditions (low_confidence_match, market_closed_or_inactive). However, it does not explicitly mention when not to use this tool compared to alternatives, e.g., for general research (deep_research) or simple lookups (ask_pipeworx).

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 openWorldHint. The description adds return field details (citing/cited DOI pair, creation date, self-citation flag) and explains the OCI format. It does not cover error behavior, but the annotations sufficiently cover safety traits.

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

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

Two sentences, front-loaded with the action, followed by the identifier format, return values, and a usage alternative. Every sentence contributes information without redundancy.

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

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

With only one required parameter, an output schema present, and strong annotations, the description is complete. It includes usage alternatives and return details, leaving no ambiguity for a simple single-record fetch tool.

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

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

The schema has zero description coverage, but the description fully explains the `oci` parameter format: 'compound ID of the form citing-DOI__cited-DOI'. This provides essential meaning beyond the schema's type and example.

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 'Fetch one citation record by its Open Citation Identifier (OCI...)' with a specific verb and resource, and distinguishes itself from sibling tools like `citations` and `references` by noting when to use those instead.

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 provides an alternative: 'Use `citations` or `references` instead when you only have a DOI.' This gives clear when-to-use versus when-not-to-use guidance.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context by noting it is a fast version and that it does not return the citing DOIs, which is 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 concise and effective: it opens with user-friendly query examples, then a crisp definition, then a tradeoff relative to `citations`. Every sentence adds value with no filler.

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

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

Given the tool has one simple parameter, a rich annotation set, and an output schema, the description fully covers purpose, scope, and relationship to a sibling. No significant information is missing for an agent to select and invoke the tool correctly.

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

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

There is only one parameter, `doi`, and the schema gives only an example. The description compensates for the 0% schema description coverage by explaining that the DOI identifies the paper and that the tool returns its citation count.

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

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

The description clearly states the tool returns the incoming citation count for a DOI, with natural-language examples. It distinguishes itself from the sibling `citations` tool as a fast version when only the number is needed, not the citing DOIs.

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

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

Explicitly says to use this tool when you only need the citation count, and points to `citations` as the alternative when citing DOIs are also required. This gives clear when-to-use and when-not-to-use guidance relative to a closely related sibling.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable context that it's the reverse direction from references, clarifying the semantic direction of the operation. However, it doesn't mention potential output format or edge cases (e.g., no citations found), but the output schema likely covers return structure.

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 but rich, using multiple example phrasings to convey the same concept. It's slightly longer than minimal but every part adds value, including the usage guidance. The front-loaded examples make the purpose immediately clear.

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-parameter tool with an output schema, the description covers purpose, usage, and direction. It fully explains what the tool does and when to use it, making it complete within its context.

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

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

The input schema only specifies 'doi' as a string without further description (0% coverage). The description compensates by repeatedly using 'DOI' in examples and clarifying that the tool operates on a given DOI. This makes the parameter's meaning clear, though it doesn't explicitly state it's a single string parameter.

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

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

The description clearly states the tool's function: it returns DOIs that cite a given DOI (incoming citations). It uses explicit verbs like 'cites' and 'reference' and provides example queries. It distinguishes itself from the sibling 'references' tool by noting it's the reverse direction.

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

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

The description gives explicit usage scenarios: 'Use for impact analysis, follow-on research discovery, "is this paper influential" questions.' It also contrasts with references, making it clear when to use this tool vs. the alternative.

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

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

Goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), sorting behavior, and return format (paired data + pipeworx:// citation URIs). 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 dense yet well-structured, front-loaded with user-intent examples for instant recognition. Every sentence serves a purpose: what, when, data specifics, sorting, return format, and efficiency gain. No filler or repetition.

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

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

For a 2-parameter tool with no output schema, the description covers all essential context: input patterns, parameter behavior, data sources, edge cases (fiscal year alignment), output ordering, and paired result structure. It leaves no ambiguity about what the tool does or returns.

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

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

Although the schema covers both parameters (type, values) at 100%, the description enriches semantics by explaining what data each type pulls (10-K metrics vs FAERS counts), clarifying the expected value formats (tickers/CIKs vs drug names), and giving concrete examples. This adds meaning beyond the schema's bare enumeration.

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 concrete query patterns ('Compare X and Y', 'X vs Y', 'which is bigger') and states the core function: side-by-side comparison of 2-5 companies or drugs in one parallel call. It clearly distinguishes itself from sequential single-pack lookups and explicitly mentions replacing 8-15 such lookups, differentiating it from sibling tools like entity_profile.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also defines what each type pulls (company vs drug) and specifies the primary-metric sorting, so an agent knows exactly when to invoke this tool over 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?

Discloses many behavioral traits beyond annotations: account/payment requirements, latency expectations (15-60s, up to ~90s), the gaps[] behavior ('never invented'), semantic excerpting of large records, resolvable citation_uri, contradictions[] for standard/thorough, and hop field. No contradiction with annotations.

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

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

The description is long but every sentence carries essential information. It front-loads the account requirement, then explains the core mechanism, use cases, alternatives, and output details. Dense but not bloated, though it could benefit from clearer paragraph breaks.

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 thoroughly explains return format (findings packet with evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), edge cases (empty gaps for unstructured topics), and operational details (latency, semantics of depth levels). Complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds the paid plan requirement for depth:thorough and reiterates hop behavior, but much of the depth semantics is already in the schema. It does clarify that depth controls facet count and iteration, adding marginal value beyond schema.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' that 'decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL.' It explicitly differentiates from siblings by noting 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data,' while 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS / "what's the world saying about X" topics, prefer ask_pipeworx.' Also gives account prerequisites and fallback behavior.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior. The description adds meaningful behavioral context: it returns top-N tools with full input schemas and curated examples, and explicitly states 'no second schema lookup needed.' This goes beyond the annotations and informs the agent of the exact return shape and direct-call readiness.

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 composed of four sentences that front-load the purpose and then add usage guidance and return details. The domain list is somewhat long but serves to clarify scope. It is efficient without being terse, though it could be trimmed slightly without loss of 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 compensates by describing the return payload: 'top-N most relevant tools with names, descriptions, and full input schemas.' It also covers the primary use case and the 'call this FIRST' workflow. This is sufficient for a read-only discovery tool, though it omits mention of the `limit` parameter (covered in schema) and any error behavior.

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

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

Schema description coverage is 100%, with each parameter (including aliases like q, task, search, description) documented in the schema itself. The tool description does not add new parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes itself as a meta-search/discovery tool among siblings, and the enumerated domains (SEC filings, FDA drugs, etc.) further clarify scope. This is more than a tautology and immediately conveys what the tool does.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available.' This gives a clear usage context. However, it does not explicitly mention when not to use it 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 is rich with behavioral context beyond the readOnlyHint annotation: it discloses the parallel fan-out across multiple sources (SEC EDGAR, XBRL, USPTO, GDELT→GNews, GLEIF), details specific return fields, and warns about the USPTO PatentsView API sunset with a 'soft-fails until reactivated' behavior. 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 densely packed with essential details: usage examples, purpose, alternatives, output components, and fallback behaviors. It front-loads example queries and purpose before diving into output specifics. A slight deduction for length and some repetition of 'names not supported' and 'ALWAYS PREFER' phrasing.

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

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

Despite lacking an output schema, the description enumerates all returned fields (cik + company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and notes limitations (patents soft-fail, names not supported). This gives an agent complete guidance for selection and invocation expectations.

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% (both 'type' and 'value' have detailed descriptions). The tool description mostly restates the same parameter information (accepted ticker/CIK, names not supported), adding no new semantic value beyond the schema. It does provide example values ('AAPL', '0000320193') but these are also present in the schema.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It specifies the resource (US public companies) and the verb ('profile'), and distinguishes it from alternatives by explicitly advising 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.'

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 triggers with example user queries ('Tell me about X', 'research Acme', etc.) and when-not conditions: 'names not supported (use resolve_entity first if you only have a name).' It also names the alternative (resolve_entity) and the broader strategy (prefer over chaining).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds useful context like deleting sensitive data and pairing with remember/recall, aligning with the annotations. No contradictions found.

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

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

Two sentences, front-loaded with the action, no wasted words. Every sentence adds meaningful information, making it highly concise and well-structured.

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

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

For a simple one-parameter tool with full schema coverage and annotations, the description fully covers purpose, usage context, and related tools. An output schema is not needed since return values are not described, but this is acceptable given the tool's simplicity.

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

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

Schema coverage is 100% with the single parameter 'key' described as 'Memory key to delete'. The description's 'by key' matches but adds no additional meaning beyond the schema, so a baseline of 3 applies.

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

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

The description uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly differentiating it from siblings like remember and recall by explicitly pairing with them. It states exactly what the tool does.

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

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

It clearly states when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data'), providing concrete scenarios. It also mentions related tools (remember and recall) but does not explicitly state when not to use it, so it's a 4 rather than a 5.

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

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

Annotations already indicate read-only/idempotent behavior. The description adds meaningful process details—it fetches the page, extracts specific elements, and outputs a standard markdown blob. This provides transparency beyond the annotations without contradicting them.

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

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

The description is appropriately sized, front-loaded with the primary action, and includes a well-organized list of use cases. Every sentence contributes meaningful information without redundancy.

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

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

With no output schema, the description adequately explains the output format ('single text blob', 'standard llms.txt markdown'). It covers the key behavioral aspects and use cases. It could mention error handling or network dependencies, but these are minor omissions given the 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?

Schema description coverage is 100%, so parameters are well-documented. The description adds minor context (e.g., url is the site to summarize, output is a text blob) but does not significantly extend the schema's parameter details. This is the baseline 3 for high schema coverage.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It also provides a concise description of the process (fetches page, extracts metadata, emits markdown) and distinguishes itself from sibling tools by mentioning competitor auditing use cases.

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

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

The 'Useful for' section provides concrete scenarios (client indexing, own project, auditing competitors). It doesn't explicitly name alternative tools, but the context is clear enough for an agent to decide when to use this tool versus related ones.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the safety profile is covered. The description adds behavioral context by specifying the output columns and the caller-specific scope ('the caller's active subscriptions'), which helps the agent know exactly what to expect.

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: the first states the action and return format, the second gives practical use cases. Every word is informative, and the structure front-loads the core verb.

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

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

This is a simple list tool with one optional boolean parameter and no output schema, so the description provides enough context by stating the return columns and use cases. Annotations handle safety, and the schema handles the parameter, making the description complete for this complexity level.

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 only parameter, include_inactive, is fully documented in the input schema with its default behavior. The description does not repeat or add parameter details, but schema coverage is 100%, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb-and-resource statement: 'List the caller's active subscriptions.' It clearly distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on read-only listing. The return fields are enumerated, leaving no ambiguity about intent.

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: 'review what you're monitoring before adding more' and 'to find an id to cancel,' which directly connect to subscribe and unsubscribe workflows. However, it does not name alternative tool IDs or state exclusions, slightly reducing explicitness.

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 read-only, idempotent, and non-destructive behavior. The description adds the batch limit of up to 50 DOIs and explicitly lists the returned fields, providing useful behavioral context beyond the annotations. 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 front-loaded with the core action and key constraints, but includes redundant paraphrases such as 'Get paper info for [DOI]' and 'bibliographic details for [paper]' before the substantive sentence. It is concise overall but not maximally efficient.

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

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

Given the simple one-parameter tool, rich annotations, and an existing output schema, the description effectively provides all necessary context: it states the input (DOIs with batch limit) and the output fields. No significant behavioral or contextual gaps remain.

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

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

The input schema fully describes the 'dois' parameter as '1-50 DOIs', and the description repeats the limit without adding new format or syntax details. With 100% schema coverage, the description offers no additional parameter meaning, so baseline 3 applies.

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

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

The description clearly states the tool retrieves bibliographic metadata for DOIs, using specific verbs like 'Get' and listing return fields (title, authors, year, journal, publisher). This distinguishes it from citation-count or reference tools, though it does not explicitly name sibling 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?

Usage is implied: when an agent needs paper metadata for DOIs, this tool is appropriate. However, the description does not explicitly state when not to use it or compare with alternatives like citations or references, so guidance remains implicit.

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

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

Beyond annotations, the description discloses rate limiting ('Rate-limited to 5 per identifier per day'), the return token behavior ('Filing without an account returns a `claim_token`'), and the internal processing cadence ('The team reads digests daily'). It also clarifies that it is free and doesn't count against tool-call quota, providing a thorough behavioral profile not captured in annotations.

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

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

The description is longer than typical but every sentence adds necessary context, covering purpose, usage, exclusions, token flow, rate limits, and roadmap impact. It is logically structured, front-loading the core purpose before caveats. It earns its length, though it could theoretically be trimmed without losing critical info.

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 the return value (claim_token), how to use it later, and what to expect ('read whether it was fixed and what changed'). It also covers prerequisites (account optional), limitations (rate limit), and scope boundaries (only Pipeworx tools). This makes the tool self-contained and complete for an agent to invoke correctly.

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

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

Schema already has 100% coverage with detailed parameter descriptions. The description adds practical usage semantics beyond schema, such as the claim_token round-trip pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and the instruction to describe issues in terms of Pipeworx tools rather than pasting end-user prompts. This enriches the semantic understanding beyond the schema alone.

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

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

The description opens with a clear action and target: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It further specifies the resource (tools served by this Pipeworx connection) and distinguishes it from other MCP servers' tools, making it unmistakably distinct from sibling research tools.

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

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

Explicit guidance is given: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This fully covers when and when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond these: data originates from CF analytics-engine, contains no PII, aggregates only (pack, tool, count), and has a caching policy (5min-1h depending on window). This is rich, non-redundant disclosure.

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

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

The description is compact, front-loaded with the core purpose, and uses a clear numbered list for use cases. Every sentence adds value: output details, use cases, data source, privacy, and caching. 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?

The tool is simple (one optional parameter, no output schema), and the description fully covers what it returns, how to choose the window, why it is useful, and its technical characteristics. It is complete enough for an agent to select and invoke the tool correctly 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?

Schema coverage is 100% and the window parameter already has an enum and description. The description reinforces window behavior by noting 'Shorter windows surface what's hot right now; longer windows show steady-state demand' (also in schema) and adds caching implications, which enriches meaning beyond the schema.

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

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

The description opens with a clear statement of what the tool does: 'What other AI agents are calling on Pipeworx right now.' It specifies the output (top tools, top packs, total call volume) and window options. This distinguishes it from siblings like discover_tools or ask_pipeworx by focusing on aggregate usage trends.

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 three explicit use cases: discovering hot data sources, confirming a canonical tool, and aligning with agent needs. It does not name specific sibling alternatives or state when not to use, but the context is clear and actionable. A score of 4 reflects strong guidance without explicit negative exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavior: no-arg trending_scan of top ~200 markets, partition-check threshold (>3pp), placeholder slug filtering, and the fill_check caveat that realizable_edge_pp <= 0 means the edge is not tradable. 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 capitalized section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence adds value, and the length is justified by the tool's complexity and the absence of an output schema.

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

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

Given the tool has no output schema, the description thoroughly covers return values (opportunities[], partition_check fields, fill_check results) and edge cases (skipped_low_similarity, placeholder fraction, thin_legs). It also mentions the relationship to sibling tools, making the context complete for an agent.

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

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

While schema coverage is 100%, the description adds meaning beyond the schema: provides example slugs, notes that full Polymarket URLs are accepted, explains the difference between event and topic modes, and describes the no-argument default behavior. This goes well beyond the schema's per-field descriptions.

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

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

The description opens with a specific verb+resource statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings by detailing its unique methodologies and explicitly comparing to related tools like polymarket_fill_risk.

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

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

Provides explicit usage guidance: 'event (recommended for a specific market)' vs 'topic (for cross-event scanning)', with concrete examples. It even tells users when to use a sibling tool ('For custom sizing use polymarket_fill_risk'), making it easy to choose the right tool.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by disclosing caching behavior ('Cached 1h at the KV level'), edge computation details ('edge_pp_net (after slippage)'), Kelly caps ('capped at 0.25'), and a warning mechanism ('Market moved X.Xpp in 24h'). It also explains model limitations, such as the unreliability of Fed signals without paid data.

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 purpose but is very long and dense, covering model family internals, response segments, diagnostics, and caching. It is well-structured with capitalized segment labels, and most sentences add substantive detail, but the length is excessive for quick agent consumption and could be trimmed without losing core guidance.

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 top-level structure (by_segment, fed_candidates/fed_note, _diagnostics) and what each segment contains. It also documents behavioral nuances like the placeholder-slug filter, partition overround, and per-leg Kelly behavior, making the tool fully understandable for an agent.

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

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

The input schema already provides 100% parameter descriptions, but the description adds meaningful grouping and rationale, such as calling min_liquidity and max_spread_pp 'TRADEABLE-EDGE KNOBS' and explaining why min_partition_leg_kelly exists. It also adds practical context like 'Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade.'

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+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also names the intended use case ('what should I bet on today') and explicitly distinguishes itself from sibling tools by framing itself as a discovery layer that avoids paging hundreds of markets.

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

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

The description gives explicit when-to-use context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains how knobs like min_liquidity, max_spread_pp, and min_partition_leg_kelly filter opportunities, but it does not name sibling tools or provide when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds rich behavioral context beyond annotations: snapshot writes are cache-miss-driven and gaps mean no scan, history is bounded by 60-day TTL, decay is computed from daily closes not intraday, and edge values are signed by trade direction. 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 well-structured with labeled sections (Args, RESPONSE, LIMITS) and front-loads the core purpose. Each sentence provides necessary detail—response fields, semantics of gaps, and limitations—without repetition or fluff. 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?

There is no output schema, so the description fully explains the response structure including tracked[], expired[], and snapshot_dates[] with field meanings and examples. It also discloses important operational constraints (TTL, cache-miss behavior, daily closes). This is complete for a tool with this complexity.

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

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

Schema description coverage is 100% for both parameters (days and window), with full descriptions and valid values. The description repeats defaults ('default 14, max 30' and 'default 1wk') and clarifies the conceptual role ('lookback', 'snapshot family'), but adds no new semantic information beyond what the schema already provides. 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 uses a specific verb phrase ('tracks edge persistence and decay') and clearly identifies the resource ('daily polymarket_edges snapshots'). It answers a precise question ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings by focusing on temporal persistence rather than just 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 a clear use case: distinguishing a fresh wide edge from a stale wide edge. It also explains what the expired[] data represents (competition clock). However, it does not explicitly contrast with sibling tools like polymarket_edges or state when not to use this tool, leaving some ambiguity for alternative selection.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds valuable behavioral context: walks the order-book ladder, returns top_of_book/vwap/slippage, detects thin legs and forced directional risk, and warns that partial basket fills convert an arb into an unhedged position. No contradiction; it extends 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?

Long but information-dense; starts with core purpose then details. Every sentence adds necessary context for two complex modes, though the wall-of-text formatting could be improved with structure. Score 4 for slightly dense structure.

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

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

No output schema exists, so description must explain return values—it enumerates all key outputs (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It also addresses edge cases (partial fills, thin books) and directs to sibling tools. Fully complete for a complex tool.

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

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

Schema covers all 4 params with 100% coverage, but description adds meaning: clarifies size_usd as 'max spend on buys, target proceeds on sells' in single-market and 'settlement notional' in basket mode; explains side default logic per mode. This goes beyond schema descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and references sibling tools (polymarket_arbitrage, polymarket_edges) as usage triggers, making its niche explicit.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books not capturable, partial fills cause directional risk), which serves as exclusion criteria.

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

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

The description goes well beyond the annotations (which only declare readOnly, openWorld, idempotent, and non-destructive hints). It discloses specific behavioral traits: two caution modes for compatibility_warning, temporal_alignment semantics, skipped_cross_type/subtype counters, and the fact that most pre-mapped topics are not currently tradeable. This gives the agent critical context that annotations cannot convey.

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

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

The description is long and dense, but every sentence earns its place: it explains the core concept, both modes, response structure, and three types of safety fields. It is well-structured with headings like 'TWO MODES' and 'SAFETY FIELDS,' and front-loaded with the core purpose. Slightly long for a tool description but justified by the tool's complexity.

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

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

Given the tool's complexity (no output schema, three optional params, and many nuanced edge cases), the description is remarkably complete. It explains what the response contains, how to interpret spread values, when compatibility_warning fires, what temporal_alignment means, and the significance of skipped_cross_type/subtype. There are no obvious gaps for an agent to make correct invocation decisions.

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

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

The input schema already documents all three parameters (100% coverage), but the description adds significant behavioral meaning: it explains how `topic` maps to 10 pre-mapped macro shortcuts, how the explicit parameters override the mapped side, and what the response contains (leg-by-leg prices, matched spread, safety fields). This transforms bare parameter names into actionable guidance.

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

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

The description opens with a precise verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from sibling tools like polymarket_arbitrage by focusing specifically on cross-venue comparisons and the same resolving question, with a detailed explanation of the two venues' different participant pools.

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

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

The description provides explicit usage modes (pre-mapped topic shortcuts vs. explicit kalshi_event_ticker + polymarket_event_slug) and strong cautionary guidance about when results should not be trusted (compatibility_warning, temporal alignment false, pre-mapped ≠ tradeable). However, it does not explicitly compare against alternative sibling tools or state when another tool should be preferred, which would push it to a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context about scoping ('anonymous IP, BYO key hash, or account ID') and the listing behavior when key is omitted, which is beyond 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?

Description is three sentences, front-loaded with the core action, and every sentence earns its place without redundant phrasing.

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 strong annotations and no output schema, the description covers purpose, usage, scoping, and complementary actions fully. No significant gaps remain.

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

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

Schema coverage is 100% and the property description already states 'omit to list all keys.' The description adds no further parameter detail 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 states a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes itself from siblings by naming remember and forget as complementary tools, and explains the optional key behavior.

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

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

Provides explicit when-to-use context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It elaborates on scenarios (target ticker, address, research notes) and pairs with remember/forget, giving clear guidance on the 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?

The annotation readOnlyHint=true claims the tool does not modify state, but the description says setting mark_read:true flags events as read and affects subsequent calls — a state-changing side effect. This directly contradicts the read-only annotation, so per the rubric transparency must be 1 and this is an annotation contradiction.

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

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

The description is three dense sentences, front-loaded with the core purpose and containing no filler. The HTTP mirror note earns its place as a practical integration detail for scripts and dashboards.

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

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

With no output schema, the description compensates by explaining that returned events carry source, citation_uri, and raw payload, and by covering filtering and mark_read semantics. It leaves limit and unread_only to the schema, which is acceptable, but a bit more detail on ordering or default behavior would make it fully 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?

All five parameters have 100% schema coverage, so the baseline is 3. The description goes beyond the schema by giving a type example ('sec_8k'), clarifying 'since' as an ISO timestamp, and explaining the semantic consequence of mark_read. This operational context adds real value.

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 opening phrase 'Pull fired events from your subscription feed' gives a specific verb+resource and clearly identifies the tool's domain. It differentiates itself from siblings like list_subscriptions and recent_changes by explaining that it returns alert events with source, citation_uri, and raw payload.

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

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

The description states filtering by type and/or since, and explicitly says 'Polls work fine', giving clear context for repeated calls. It also names the HTTP mirror for scripts/dashboards, which is a useful alternative. It does not explicitly contrast with sibling tools, so it falls just short of a 5.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses significant behavioral context: it fans out to three external sources, describes a fallback chain (GDELT→GNews), notes the PatentsView API sunset causing soft-fail until reactivated, and describes the return structure (changes[] grouped by source, total_changes count, pipeworx:// URIs). 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?

Though longer than typical descriptions, it is dense and logically organized: query examples → core function → source fan-out → parameter syntax → return value → alternative tool. Every sentence provides unique information; no filler or repetition of annotations/schema.

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

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

For a tool with no output schema, the description explains what the tool returns, the sources and fallbacks, parameter formats, and known limitations (USPTO soft-fail). It also names the sibling tool to use for a different use case. This is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete examples for `since` ('7d', '30d', '3m', '1y'), clarifying that `value` can be a ticker or zero-padded CIK (with example '0000320193'), and recommending a default parameter ('30d' or '1m'). This practical context enhances the schema.

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

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

The description opens with concrete natural-language examples ('What's new with X', 'updates on Acme') then clearly defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It specifies the exact sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly differentiates from the sibling `entity_profile` by naming it as the static-profile alternative.

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 this tool vs. alternatives: 'Use entity_profile instead when you want the static profile...'. It also provides practical guidance like typical monitoring windows ('Use "30d" or "1m" for typical monitoring') and describes fallback behavior (GDELT preferred, GNews when rate-limited or 5xx), giving the agent clear decision 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 readOnly, idempotent, and non-destructive behavior. The description adds meaningful semantic context by clarifying that the tool returns the paper's reference list, which is not implied by the tool name alone. It does not contradict annotations.

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

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

The description is two sentences, front-loads the phrasing with common user queries, and efficiently communicates the core function and use cases without any wasted words.

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

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

With one simple parameter, comprehensive annotations, and an existing output schema, the description fully covers the necessary context. It explains what the tool does and when to use it, leaving no significant gaps.

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

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

The only parameter 'doi' is not described in the schema (0% coverage), but the description effectively conveys that 'DOI' refers to the paper whose references are to be retrieved, through phrases like 'given DOI' and the query examples. This is adequate for a single parameter.

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 that this tool returns the references/bibliography (DOIs cited BY the given DOI), using explicit query examples like 'What does paper [DOI] cite'. It distinguishes itself from sibling tools by specifying the direction of the citation relationship, which is critical for citation-graph traversal.

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

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

The description provides clear usage context: 'Use for citation-graph traversal, literature review, source tracking.' However, it does not explicitly state when NOT to use it or name alternatives (e.g., the sibling 'citations' for finding papers that cite a given DOI).

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the bar is lower. The description adds value by revealing it's a 'fast' variant and clarifies the count is 'outgoing,' setting expectations for performance and direction.

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 compact sentences with natural-language examples; no filler. The phrase 'outgoing reference count' is a precise summary.

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 an output schema and strong annotations, the description covers purpose, usage guidance, and parameter semantics. Nothing essential is missing.

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

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

The description explains that the `doi` parameter refers to a paper identifier in context ('paper [DOI]'), and the example in the schema supplements formatting. With 0% schema coverage, this is enough to infer what to pass.

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

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

The description uses specific verbs like 'count' and 'has' to indicate a numeric result, and clearly identifies the resource as a paper's DOI and its outgoing references. It distinguishes from the sibling `references` tool by noting it's the 'fast version' for just the number.

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 'Fast version of `references` when you only need the number,' naming the alternative and the condition. This provides clear guidance on when to use this tool instead of the full reference list.

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

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

Annotations indicate a non-read-only, idempotent, non-destructive write operation, and the description adds important context: key-value scoping by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. This goes beyond the annotation hints without contradiction.

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

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

The description is concise at four sentences, front-loads the main action, and every sentence adds value—usage examples, scoping, retention, and pairing with sibling tools. No fluff.

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

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

For a simple two-parameter tool with no output schema, the description fully covers purposes, usage, persistence, and relation to siblings. It is complete for the agent to decide when and how to invoke it.

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

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

Schema description coverage is 100%, with both key and value already documented. The description reinforces the key-value concept with examples but adds minimal new parameter-level detail, 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's function: 'Save data the agent will need to reuse later.' It uses a specific verb (save) and a clear resource (data), and distinguishes from sibling tools by mentioning recall and forget as paired operations.

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

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

Explicit when-to-use guidance is provided: 'Use when you discover something worth carrying forward' with concrete examples like ticker, address, preference. It also tells the agent to pair with recall and forget, offering clear alternatives.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description provides rich behavioral context: it states identifiers are labelled with their source, unresolved identifiers are explicitly listed under 'unresolved', and that LEI/FIGI enrichment degrades gracefully if external sources are unavailable. This fully discloses the tool's behavior and edge cases.

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

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

The description is well-structured: it opens with example queries, gives a clear purpose statement, then details supported types and edge-case behavior. Every sentence earns its place, and the length is appropriate for the tool's complexity. It is front-loaded with the most important guidance ('Use FIRST') and avoids redundancy.

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

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

Given the tool's two distinct entity types, multiple identifier sources, and no output schema, the description is thoroughly complete. It covers inputs, outputs, sources, fallback behavior, and error handling (unresolved identifiers). An agent has all necessary information to select and invoke the tool correctly without additional lookup.

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, but the description adds significant meaning: it explains the value formats for each type (ticker, CIK, company name for 'company'; brand or generic name for 'drug') and provides concrete examples. This goes beyond the schema and helps the agent correctly format inputs.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers. It provides specific verbs and resources, and distinguishes itself from siblings by listing supported entity types and the exact identifiers returned (CIK, ticker, LEI, FIGI, RxCUI). The inclusion of example queries makes 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 instructs 'Use FIRST whenever you have a name but need an ID,' which is direct usage guidance. It also explains when each type is appropriate (company vs. drug) and notes that it replaces 2-3 manual lookups, making it clear when to choose this tool over alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds behavioral details beyond that: it probes with ai_visibility_check, ranks results by score, and returns a list with score, confidence, and signal density per entity. This gives useful process and output information. It does not mention rate limits or potential cost, so not a 5.

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

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

Three sentences: the first states the core function, the second explains mechanics and ranking, the third gives a use case and the return structure. Every sentence is valuable and there is 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 complex tool with no output schema, the description covers the main aspects: the comparison logic, the underlying probe, the ranking, and the return format. The schema handles parameter details and annotations handle safety. This is complete enough for an agent to understand what the tool does and 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 description coverage is 100%, and each parameter already has a clear description. The tool's description does not add anything beyond the schema about parameters, 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 compares AI visibility across multiple entities side-by-side. It explicitly describes the process (probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized), distinguishing it from the single-entity sibling ai_visibility_check.

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

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

Provides a concrete use case: competitive AI-marketing audits, with an illustrative question. It implies that ai_visibility_check is for single entities and this tool is for multi-entity comparison, but it does not explicitly state when not to use it or mention alternative comparison tools like compare_entities.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond these: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, sources_failed will list timeouts, and only the NPM ecosystem is supported in v1. These are non-obvious behaviors that help the agent anticipate side effects and limitations.

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. Each sentence carries meaningful information: the first defines the tool, the second gives usage context, the third lists return fields, the fourth notes ecosystem limits and alternatives, and the fifth explains failure behavior. No fluff or repeated 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?

There is no output schema, so the description takes on the burden of explaining return values. It lists the summary block fields, per-advisory details, links, and alternatives. It also covers timeout behavior, partial failure handling, and ecosystem constraints. For a composite tool with external service dependencies, this is remarkably complete.

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

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

Input schema covers 100% of parameters (package and version) with clear descriptions. The description does not add much extra parameter-specific information beyond what the schema already provides; it only reiterates the npm ecosystem scope. With full schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states it is a 'Composite "should I add this npm package to my project" check in ONE call' that fans out across deps.dev and bundlephobia. It specifies a concrete action, resource (npm packages), and scope (license, advisories, bundle size, etc.), distinguishing it from sibling tools that are narrower or different in focus.

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 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', clarifying when not to use this tool and what to use instead. This meets the 'explicit when/when-not/alternatives' criterion.

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 mark this as read-only/idempotent, the description adds substantial technical behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and output including character offsets and similarity scores. This is beyond what annotations convey.

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

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

Five sentences, each carrying distinct value: purpose, usage, output details, pairing, and technical limitations. No redundancy; information is front-loaded with the core purpose first.

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, use case, return values (top-N passages with offsets and similarity scores), technical mechanism, and limitations (200K cap). Since there is no output schema, it sufficiently explains what the agent can expect.

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

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

Schema coverage is 100% with descriptions for all parameters. The tool description adds useful examples for 'text' (e.g., SEC 10-K body, article) and clarifies the query's natural-language intent, but it doesn't significantly expand beyond the schema's parameter explanations.

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

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

The description clearly states a specific verb+resource+scope: 'Semantic search INSIDE a fetched record.' It distinguishes from siblings by focusing on searching within an already-fetched document and explicitly pairs with ask_pipeworx_grounded, clarifying its complementary role.

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

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

The description gives an explicit when-to-use: 'Use when the record is too big to cram into the prompt.' It also explains the value (saves context, returns only relevant passages) and mentions a paired tool, providing clear guidance on 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?

Adds meaningful behavioral context beyond annotations: OAuth requirement, persistent feed always on, SMS delivery constraints (phone verification, 10/day cap), and the return of a subscription id. It does not contradict the annotations, though it omits webhook details and lists only three of the five supported types.

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, then organizes types and delivery channels. It is longer than ideal but every sentence provides distinct 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?

For a complex tool with nested delivery objects and five enum types, the description covers account requirements, return value, and main channel constraints. However, it omits webhook as a delivery channel and does not mention patent_grant or clinical_trial despite listing 'Supported types', leaving gaps that the schema partially fills.

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

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

The description adds concrete JSON examples for type-specific params (e.g., items:["5.02"] = officer change, params:{topic:"fed"}, series_id:"UNRATE") and delivery channel constraints. The schema already provides detailed descriptions, but the extra examples meaningfully help an agent construct correct parameters.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' and states the new subscription id is returned. This clearly distinguishes it from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

The description clearly identifies the tool's role—creating subscriptions—and gives prerequisites (OAuth account required; anonymous/BYO cannot persist). It does not explicitly name alternatives like list_subscriptions or unsubscribe, but it states when the tool is appropriate and provides delivery-channel context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it returns category-bucketed examples with exact tool+argument shapes, drawn from a live catalog of thousands of tools, and explains that omitting topic gives the full spread. This goes beyond the annotations without contradicting them.

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

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

The description is a single dense paragraph but front-loaded with example queries and immediately states the tool's purpose. Every sentence contributes, covering categories, output shape, call patterns, and usage timing. Slightly long but well-structured and free of 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 tool with one optional parameter and no output schema, the description is thorough. It explains what the tool returns (category-bucketed examples with tool+argument shapes), how to invoke it (with or without topic), and when to use it (first when onboarding). No significant 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?

The schema covers 100% of parameters, but the description enriches the meaning of `topic` by giving examples ('finance', 'pharma', 'betting') and clarifying that omitting it yields a cross-category spread. This adds practical usage context beyond the schema's enum-style description.

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

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

The description clearly states a specific verb and resource: it 'Returns category-bucketed example questions' and identifies itself as 'the onboarding entry point'. It distinguishes from siblings by focusing on helping users discover what to ask and how to call meta-tools, unlike discover_tools which might have a different focus.

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

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

The description gives explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to call with or without the topic parameter. However, it does not explicitly mention when not to use it or mention alternative tools by name, so it misses the top tier.

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

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

The description adds substantial behavioral detail beyond the annotations: ownership enforcement, the soft-delete behavior (deactivated not deleted), and the continued availability of historical events via recent_alerts. This meaningfully informs the agent about side effects, which is especially valuable given the mutation context (readOnlyHint=false).

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

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

Three sentences, each earning its place: the action, the ownership constraint, and the deactivation behavior. Front-loaded with the verb, no redundant 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 cancellation tool with one parameter and no output schema, this description is complete: action, constraint, side effect, and historical data implications. The annotations already cover idempotency and non-destructiveness, so the description does not need to repeat them.

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 the id parameter with a clear description, so baseline is 3. The description adds crucial semantics by stating 'Ownership is enforced — you can only cancel your own subscriptions,' which tells the agent that the id must refer to the caller's own subscription. This extra context raises the score.

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

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

The description uses a specific verb ('Cancel') with a specific resource ('a subscription by id') and clearly distinguishes this from sibling tools like subscribe and list_subscriptions. The primary purpose is immediately understandable.

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: ownership is enforced, and cancellation is a deactivation rather than deletion. It implies when to use (you have a subscription you want to cancel) and mentions recent_alerts as a way to still access historical data, but it does not explicitly name alternatives or exclusion criteria beyond that.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds crucial behavioral details: meaning of could_not_verify vs. unsupported, presence of verification_error, routing logic between structured and grounded pipelines, and that it returns a verdict with citation. This is valuable beyond annotation hints.

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

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

The description is a dense paragraph with multiple clauses, but each part contributes: query examples, usage, pipeline routing, return values, and error semantics. It is longer than ideal but well-structured and free of redundancy.

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

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

Despite no output schema, the description fully explains return values (verdict enum, value, citation, reasoning) and error semantics. It covers scope, edge cases, and integration (replaces sequential calls), leaving no significant gaps for evaluation.

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 clear descriptions for both parameters, so baseline is 3. The description adds minor context like 'exact percent-delta math' and natural-language phrasing but doesn't introduce parameter semantics not already in the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It gives specific verb 'verify' and resource 'claim', plus example query phrases, and distinguishes it from other tools by focusing on fact-checking with verdict 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?

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates handling of company-financial claims vs. other claims, effectively guiding when to use this tool vs. alternatives like deep_research or ask_pipeworx_grounded.

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