crossref

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds valuable context beyond annotations: the default model (Workers AI Llama-3.3-70b, free), cost implications of passing _apiKey ("BYO key — you pay Anthropic directly"), and the return structure. This is meaningful behavioral disclosure without contradicting annotations.

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

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

The description is four sentences, logically front-loaded: core capability, default model, optional key behavior, return format, and use cases. Every sentence contributes unique information; there is no fluff or repetition of schema/annotations.

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 moderate complexity, the description covers all key aspects: purpose, parameter behavior (defaults, optional key, cost), output shape (per-model object + combined view), and use cases. There is no output schema, so the explicit return format description fills that gap. Annotations cover safety/idempotency. The description is sufficient for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description adds extra meaning by explaining the default model when 'models' is omitted (not fully in schema) and the cost/fund-flow for _apiKey. This nudges it above the baseline of 3, though it doesn't deeply expand every 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 opens with a specific verb+resource: "Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model." This clearly distinguishes it from sibling tools like ask_pipeworx (which asks questions) and compare_entities (which compares entities). The scope and output are immediately clear.

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

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

The description explicitly states when to use the tool: "Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring." It also provides invocation guidance (default model, optional _apiKey to include Anthropic). However, it does not name alternatives or explicitly say when not to use it, so it misses the high bar of 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context: it routes across thousands of tools, fills arguments, returns stable pipeworx:// citation URIs, and works in one fast call. However, it doesn't disclose edge cases like what happens when no matching tool exists, which would be useful but is not a major gap given the annotations.

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

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

The description is well-structured and front-loaded with the core purpose, but it is overly verbose with redundant marketing language ('PREFER OVER WEB SEARCH', 'START HERE for most questions — this is the default entry point'). Examples are useful but could be trimmed. It earns a 3 because structure is good but conciseness suffers from repetition and promotional tone.

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 that routes to over 5,500 sources, the description is quite complete: it explains the routing behavior, return format with citations, tier availability, and when to use alternatives. With no output schema, it still conveys what the answer looks like. Some details about rate limits or failure modes are absent, but this is a read-only tool with strong annotations, so the description covers the essential contextual needs.

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

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

The input schema lists six parameters but all are aliases for the same question field. The description clarifies this by stating 'Accepts query, q, prompt, text, input as aliases' and notes that 'question' is the canonical name. This adds meaning beyond the schema's terse alias descriptions, so the baseline of 3 is reasonably elevated.

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

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

The description clearly states what the tool does: it routes questions to one of 5,529 tools across verified sources and returns structured answers with citations. It uses a specific verb ('routes') and resource ('Pipeworx'), and differentiates from siblings by explicitly 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?

The description explicitly instructs to prefer this tool over web search for factual questions, declares it the default entry point that works on every tier, and provides clear when-to-step-up guidance by naming ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part queries. It also gives concrete example queries, making usage conditions unambiguous.

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

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

Annotations already cover readOnly, idempotent, non-destructive. The description adds substantial context: beta status, live candidate routing improvements when under test, current parity with ask_pipeworx, and the comparison mechanism. It also clarifies 'Falls back to nothing — this IS a full working router', preventing misconceptions.

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, all purposeful and front-loaded with the beta designation. The second sentence includes a specific date and detail about candidate retirement, which is slightly dense but relevant. No waste, though could be slightly tighter.

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 required parameter and no output schema, the description fully covers what the tool is, how it differs from the stable version, current operational state, and usage guidance. It is contextually complete.

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

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

Schema coverage is 100% with clear descriptions of the 'question' parameter and its aliases. The description adds no parameter-specific details, which is acceptable given the high schema coverage. 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 this is 'Beta version of ask_pipeworx: identical universal router' with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by mentioning 'candidate routing improvements' and being 'the experimental edge'.

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 it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router. This provides clear when-to-use guidance and implicitly differentiates from the stable alternative.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, but the description adds significant context: one extra LLM call, structured return with evidence/confidence/refusal_reason, explicit refusal reasons, and the fact that it only uses tool-result content. This goes well beyond annotation metadata and clarifies failure modes.

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

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

The description is relatively long but information-dense, front-loaded with the core purpose, then mechanics, return format, and usage guidance. Every sentence contributes value, though it could be slightly more compact. The structure is clear and logical.

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 provided, the description fully specifies the return structure, refusal reasons, and success/failure behaviors. It also covers routing mechanics, cost, and usage contexts. The tool's complexity is well accommodated without leaving critical 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 schema covers all 6 parameters with descriptions (100% coverage), listing aliases for the same natural-language question. The description adds that the tool 'fills arguments' during routing, but does not expand the meaning of the question parameter itself. Per the calibration baseline for high schema coverage, a 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 the tool's function with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It explains it routes to tools, fetches data, and extracts answers exclusively from tool results. It also distinguishes from the sibling ask_pipeworx by emphasizing refusal behavior and grounded extraction.

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 instructs when to use: 'Use whenever an answer will be quoted, cited, or acted on...' and when not to: 'prefer ask_pipeworx for casual lookups.' It names the alternative tool and provides a cost tradeoff, giving clear guidance on selecting this tool versus 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses extensive behavioral traits: resolver contract with confidence levels and alternatives, low-confidence short-circuiting, closed-market status, wide-spread illiquidity flag, cancellation rule risk, news fallback behavior, and response shapes. This far exceeds what annotations provide and gives 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 clear section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with the core purpose. It is dense with valuable detail, though slightly oververbose in repeating fan-out examples; still, every section adds substantive operational knowledge.

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

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

Given the tool's complexity (multiple response shapes, fallback paths, error statuses) and the absence of an output schema, the description is exceptionally complete — covering market data, analysis warnings, evidence structure, resolver confidence, parent events, news fallbacks, and even settlement-rule risk. No obvious gaps that would lead an agent to misuse the tool.

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

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

The input schema already covers all three parameters with 100% description coverage, including examples for market and defaults for depth and include_raw. The description adds no parameter-specific detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further enumerates concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and distinguishes itself from sibling tools by focusing on data-backed research rather than arbitrage, edges, or tracking.

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

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

The description explicitly states when to use the tool with the 'Use for...' directive, providing clear context. However, it does not mention alternative tools or when NOT to use it, so it falls short of the highest bar that requires explicit when-not/alternatives.

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

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

The description discloses data sources (SEC EDGAR/XBRL, FAERS), correct handling of off-calendar fiscal years, sorting by primary metric, and citation URI returns. This goes far beyond the annotation hints and gives the agent real behavioral expectations.

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

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

The description is long but every sentence carries meaningful information—query patterns, data sources, edge-case handling, output structure, and efficiency. It is front-loaded with examples and uses formatting sparingly, making it dense 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?

Even without an output schema, the description covers what is returned (paired data, citation URIs), how results are sorted, and what data sources feed each entity type. This is a complete picture for a tool of 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 coverage is 100% with clear parameter descriptions, so baseline is 3. The description adds type-specific behavioral detail (e.g., company pulls 10-K revenue/net income, drug pulls FAERS counts), enhancing semantic understanding beyond the schema.

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

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

The description opens with concrete query patterns and states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call'. It distinguishes the tool from sequential single-pack lookups by emphasizing parallel execution and specific entity types. This makes the tool's scope unmistakable.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. The described query examples and the note about replacing 8–15 sequential lookups further reinforce the intended usage context.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses account requirements and paid tiers, latency expectations, semantic excerpting rather than head-truncation, a hop field and citation_uri only when fetchable, explicit gaps[] for unanswered facets, and contradictions[] for standard/thorough. These are behavioral traits not inferable from 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 lengthy but every sentence adds unique value—account context, alternatives, return format, depth nuances, latency, and edge-case behavior. It is front-loaded with critical constraints (account requirement, alternative tool) before diving into details, so the length is justified and efficiently structured.

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

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

With no output schema, the description carries the full burden of explaining return values and does so thoroughly: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, and gaps[]. It also covers latency, depth behavior, semantic excerpting, and the account/plan gate, making it complete for the tool's complexity.

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

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

Schema coverage is 100% and the schema already documents both 'question' and 'depth' with rich detail. The description adds value by noting 'depth:"thorough" needs a paid plan' and emphasizing that 'Broad/multi-part is fine — decomposition is the point', which clarifies parameter usage 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 performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains the decomposition and parallel-routing behavior. It explicitly distinguishes itself from open-web search and names ask_pipeworx as the alternative for single lookups, so sibling differentiation is strong.

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/alternatives: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also states the tool is 'Best for broad/multi-part questions over structured data' and explains depth-level selection with gap recovery and lead-chasing 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 declare readOnlyHint=true and idempotentHint=true, so the agent knows it's safe. The description adds behavioral detail: returns top-N results with full input schemas and curated examples, ready to call directly without a second schema lookup. This goes beyond the annotations to clarify the output and convenience behavior.

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

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

The description is three sentences, each adding distinct value: purpose, usage context, and return behavior. It is front-loaded with the core function and ends with a clear 'call first' directive. 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 discovery tool, the description covers purpose, usage, output format, and provides a concrete instruction for when to invoke it. The schema covers all parameters at 100%, and annotations cover safety, so the description is sufficient for an agent to select and call it correctly.

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

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

Schema description coverage is 100%: the schema documents query and its aliases (q, task, search, description) and limit with default/max. The description only restates that you describe the data/task, adding no new parameter semantics beyond what the schema already provides. Baseline 3 applies.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It further specifies the categories of data covered and describes the return format (top-N tools with schemas), distinguishing it from sibling tools like search_within or deep_research which perform direct searches/research rather than tool discovery.

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

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

The description explicitly provides usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and instructs to 'Call this FIRST when you have many tools available...'. This gives clear guidance on when to use it, though it doesn't explicitly name sibling alternatives or state when not to use it, so a 4 rather than 5.

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

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

Beyond annotations, the description discloses parallel fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; lists explicit return fields; and notes the USPTO PatentsView API sunset with soft-fail behavior. It also explains input constraints (ticker or CIK only). No contradiction with readOnly/idempotent hints.

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

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

The description is long but dense; every clause adds useful context: example queries, sources, return fields, limitations, and usage guidance. It is well-structured with semicolons and a clear progression, though slightly verbose.

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

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

Despite no output schema, the description covers inputs, examples, output structure (e.g., cik, recent_filings up to 5 with URIs, fundamentals sorted fields, patents, news, LEI), known failure modes, and alternative tool usage. Comprehensive for a complex multi-source 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 already provides full descriptions for both parameters, including examples and unsupported name constraint. The description repeats this information but does not add new semantic meaning. Schema coverage is 100%, 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 uses specific verbs ('profile', 'brief', 'research') and states it provides a 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes from sibling single-pack lookup tools via 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news 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?

Explicitly states when to use this tool: 'when the user asks for a holistic view' and 'ALWAYS PREFER over chaining single-pack lookups.' Also gives an alternative: 'use resolve_entity first if you only have a name,' indicating when this tool is not appropriate.

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 readOnlyHint: false, so the description carries a lower burden. It adds context about deleting previously stored memory and clearing sensitive data, but these are use-case clarifications rather than deeper behavioral disclosures (e.g., irreversibility, confirmation steps). No contradiction exists, but the added value is modest.

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

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

The description is two sentences, front-loaded with the primary action, and contains no filler. Every sentence earns its place: the first states purpose, the second provides usage context and related tools.

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

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

For a one-parameter, non-output-schema tool with annotations covering destructive behavior, the description is sufficiently complete. It explains what the tool does, when to use it, and how it relates to siblings. No major gaps remain for an agent to invoke it correctly.

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

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

Schema description coverage is 100% — the only parameter 'key' is described as 'Memory key to delete.' The tool description adds no further semantic nuance beyond restating the key concept, so the schema adequately handles parameter explanation. 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: 'Delete a previously stored memory by key.' This clearly distinguishes the tool from siblings like 'remember' (store) and 'recall' (retrieve), leaving no ambiguity about its function.

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

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

The description provides explicit conditions for use ('when context is stale, the task is done, or you want to clear sensitive data') and names related tools ('Pair with remember and recall'). It lacks a direct 'when not to use' clause, so it doesn't fully meet the 5-level criteria, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral context by stating it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', which clarifies the network access and output nature. It does not mention edge cases or rate limits, but given annotation coverage, this is solid.

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

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

The description is concise and well-structured: it leads with the primary purpose, explains the process, states the output format, and lists use cases. Every sentence contributes value without redundancy or fluff.

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

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

The tool is simple (2 params, no output schema), annotations cover safety, and the description fully explains the purpose, process, output, and use cases. 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 description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond the schema; it only mentions 'any URL' in passing. No additional semantic value is provided for url or max_links.

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

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

The description states a specific verb+resource+scope: 'Generate a production-ready llms.txt file for any URL' and explains the process and output. However, it does not explicitly distinguish itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence, so it misses the top score for sibling differentiation.

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

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

The description provides clear usage contexts ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). It lacks explicit when-not-to-use or alternative tool references, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context beyond this by specifying the result limit ('5 most recent works') and the fields returned (titles, authors, DOIs, publication dates), which are useful for the agent's expectations.

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

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

The description is two sentences, front-loaded with the core action and scope. Every word contributes value, with an example ISSN and a clear list of returned fields. No fluff or redundancy.

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

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

The tool is simple with one parameter, an output schema exists, and annotations provide safety profile. The description adequately covers the purpose, result set size, and returned fields, making it complete for an agent to invoke correctly.

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

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

The schema provides 100% coverage for the only parameter 'issn' with a description and example. The description reinforces the ISSN-based lookup but does not add new semantic detail beyond the schema. Baseline 3 is appropriate given 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: 'Get the 5 most recent works from a journal by ISSN'. It specifies the verb, resource type (works), and input identifier (ISSN), and the scope (5 most recent). This distinguishes it from siblings like get_work (single work) and search_works (broad search).

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

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

The description gives a clear context for use: obtaining recent journal works via ISSN. It does not explicitly mention alternatives or exclusionary cases, but the specificity of the use case provides sufficient guidance for when to select this tool among the siblings.

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

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

Annotations already declare the tool as read-only, idempotent, open-world, and non-destructive. The description adds a concrete DOI example and enumerates the returned fields, which gives behavioral context beyond the safety annotations. No contradiction exists.

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

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

The description is two sentences, front-loaded with the verb and resource, and contains no redundant or vague wording. It is appropriately 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?

The tool is simple with one parameter, rich annotations, and an output schema. The description covers the purpose, the lookup key, and the type of data returned, making it complete for an agent to invoke correctly.

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

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

The input schema fully describes the single 'doi' parameter with type, description, and example. The description repeats this example and adds no new parameter-level information, so the baseline 3 applies.

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

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

The description uses a specific verb 'Get' with a clear resource 'full metadata for a publication by DOI' and lists returned fields. This distinguishes it from sibling tools like search_works (which searches without a DOI) and get_journal (which targets journals).

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 indicates the use case: retrieving metadata when you have a DOI. It provides a concrete example. However, it does not explicitly mention when not to use it or compare alternatives, so it lacks exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing safety. The description adds valuable behavioral context by specifying the exact return fields and the default behavior of listing only active subscriptions, going beyond the annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence adds value—return fields and usage guidance. No filler or redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers the purpose, return structure, and practical use cases. The annotations address safety and idempotence, 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 input schema includes a full description for the only parameter (include_inactive), so schema coverage is 100%. The description does not add additional parameter semantics beyond the schema, though it reinforces the active-only default. 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 'List the caller's active subscriptions' with a specific verb, resource, and scope. It also lists the returned fields, making the tool's function unambiguous and distinct from sibling tools like subscribe and unsubscribe.

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 scenarios: 'review what you're monitoring before adding more' and 'find an id to cancel.' However, it does not name alternatives or provide when-not guidance, so it lacks the explicit exclusion criteria required for a 5.

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

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

Annotations are all false, providing no safety signals, so the description carries the full burden. It discloses crucial behavioral traits: returns a claim_token for later status checks, is rate-limited to 5 per identifier per day, is free, doesn't count against quota, and the team reads digests daily. This goes far beyond structured fields.

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

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

The description is longer than average but every sentence earns its place, covering usage criteria, exclusions, claim_token flow, rate limits, and free usage. It is front-loaded with the core purpose in the first sentence and remains organized. Slightly verbose, but justifiably so for a multi-faceted feedback tool.

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

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

With no output schema, the description adequately covers the return behavior (claim_token for anonymous filing, status/change resolution on later lookup). It explains the full feedback lifecycle, including rate limits and roadmap impact, making it complete for a complex 4-parameter tool with nested objects and optional params.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context: explains that filing without an account returns a claim_token and how to use it later ('pass it back as pipeworx_feedback({claim_token:"pwfb_…"})'). It also advises describing issues 'in terms of Pipeworx tools/packs', which guides the message and context parameters. This is a clear improvement over raw schema.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from siblings by focusing exclusively on feedback for Pipeworx tools, with no overlapping tool among the siblings.

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

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

Provides detailed when-to-use guidance: '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 explicitly disambiguates from other MCP servers and states what not to do ('don't paste the end-user's prompt'), 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?

Annotations already declare read-only and idempotent. The description adds meaningful context: self-aggregating signal, derived from CF analytics-engine, no PII, and caching behavior (5min-1h depending on window). This goes beyond annotations and gives the agent useful expectations about data freshness and privacy.

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

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

Four sentences with a strong lead, a concise output summary, bulleted use cases, and a compact caveat set. Every sentence earns its place; no fluff or repeated schema 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 read-only tool with one optional parameter and no output schema, the description covers purpose, outputs, use cases, privacy, and caching. It is fully adequate for an agent to understand 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 coverage is 100% and the window parameter has a clear enum and default. The description adds interpretive value by explaining the trade-off between shorter and longer windows, which is not present in the schema's enum definition.

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

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

The description opens with a clear, specific purpose ('What other AI agents are calling on Pipeworx right now') and lists exact outputs ('top tools, top packs, and total call volume'). It clearly distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on aggregated trending signal.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical tools, aligning with agent needs) and explains how window choice affects results ('shorter windows surface what's hot right now; longer windows show steady-state demand'). It doesn't name specific alternatives for exclusion, but gives clear guidance on when to use it.

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

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

Annotations already declare read-only/idempotent behavior; the description adds substantial operational context: partition filter drops placeholder slugs and returns null above 20%, semantic anchor requires ≥0.30 Jaccard similarity and surfaces skipped_low_similarity, and fill check warns that realizable_edge_pp ≤0 means do not trade. 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?

Long but front-loaded with purpose and argument modes. Every sentence contributes operational detail (filters, thresholds, response fields) and the structure uses bolded labels. Slightly verbose but 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?

Despite no output schema, the description specifies response fields (opportunities[], partition_check, fill_check details) and links to fill_risk for sizing, making it self-sufficient for invocation and interpretation.

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

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

Schema covers both params with descriptions, but the description adds concrete examples (event slugs like 'fed-decision-may-2026', seed questions like 'Strait of Hormuz traffic returns to normal'), mode semantics, accepted URL format, and the relationship between event/topic, going well beyond the schema.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (trending_scan, event, topic) and references polymarket_fill_risk for sizing, separating it from siblings.

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

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

Provides explicit usage guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It marks event as recommended for a specific market, explains when cross-event mode is better, and directs custom sizing to polymarket_fill_risk.

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 goes well beyond these by detailing model-family mechanics (e.g., per-sport α values), per-opportunity fields (edge_pp_net, kelly_fraction_half capped at 0.25), tradeable-edge knob behavior, 24h-move warnings, and KV-level caching (1h keyed on all knobs). It also surfaces edge cases like the unreliable Fed signal at meeting-month horizons. 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 highly dense and logically structured: model families are numbered, response segments are grouped, and the top-level response layout is provided. Every sentence carries unique domain-specific information (e.g., per-sport α, placeholder-slug filtering, diagnostics funnel counters). It could be slightly more scannable with headers, but there is no redundancy or filler.

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

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

Given the tool's complexity (9 knobs, three model families, no output schema), the description thoroughly compensates. It specifies the top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics), lists exact per-opportunity fields, explains why segments can be empty, and documents filter interactions. An agent has enough information to invoke the tool and interpret its response without ambiguity.

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

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

The input schema already provides descriptions for all 9 parameters, so the baseline is 3. The description adds meaningful beyond-schema context: it explains how min_partition_leg_kelly applies to basket legs rather than the parent level, why partition_overround parent kelly_fraction_half is always 0, how slippage_pp is deducted from raw edge, and the interplay of min_liquidity/max_spread_pp as tradeability filters. This lifts it above the baseline.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly positions itself as an opportunity-discovery tool for daily betting, which distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker. The statement 'without paging hundreds of markets' adds practical value.

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 frames the use case ('what should I bet on today') and tells agents they can discover opportunities without exhausting pagination. It also explains when certain outputs appear (Fed candidates are excluded from ranking, diagnostics explain empty segments), but it does not explicitly name sibling tools or state when NOT to use this tool in favor of another.

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 readOnlyHint annotation by explaining the response shape (tracked, expired, snapshot_dates), the signed edge_pp_net semantics, snapshot write behavior (cache-miss), and historical limits (60-day TTL, start time). This provides deep behavioral context without contradicting the annotations.

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

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

The description is long but structured into Args, RESPONSE, and LIMITS sections. The Arg section repeats schema information, but the response and limits sections are essential due to the lack of an output schema. Overall, it is dense but well-organized.

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

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

The description fully accounts for the tool's complexity: no output schema is compensated by a detailed response breakdown, data gaps are explained via snapshot_dates, and edge cases like TTL and daily-close computation are disclosed. It leaves little ambiguity for an agent.

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

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

Schema coverage is 100% with both parameters described. The description repeats the defaults and adds 'max 30' but omits the min clamp of 2 that the schema provides. It adds minimal value beyond the schema's already-detailed parameter descriptions.

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

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

The description clearly defines the tool as 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges (which likely shows current edges) by focusing on the time-series aspect.

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

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

The description implies usage for evaluating edge age with the sentence 'a fresh wide edge and a 3-week-old wide edge are different trades', but it does not explicitly name alternatives or state when not to use it. The context is clear but lacks explicit 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 goes far beyond by detailing exact return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and explaining behavioral nuances like 'forced_directional_risk naming the legs most likely to strand you unhedged.' 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 dense—every sentence adds distinct value. It front-loads the core purpose, then methodically covers constraints, both modes, return values, and usage context. No fluff or repetition; the length is justified by the tool's complexity.

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

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

With no output schema, the description fully inventories return values for both modes (e.g., theoretical_sum, capture_ratio, thin_legs, max_clean_notional_usd). It explains the risk model and the meaning of key terms like 'settlement notional.' For a max-complexity tool (two modes, 4 params), this is complete.

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

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

While schema coverage is 100%, the description adds meaning beyond schema: it explains that `size_usd` is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S' in basket mode, plus clarifies `side` defaults for each mode. This interpretive layer is not 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market and basket modes, and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate when this tool is used.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Even explains the risk of partial fills converting an arb into unhedged directional positions, which justifies the tool's necessity.

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

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

Despite having annotations (readOnlyHint=true, idempotentHint=true), the description adds extensive behavioral context: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs. with skipped_cross_type:0), temporal_alignment field, skipped_cross_type/subtype counters, and the direction of the spread (Kalshi − Polymarket). It also transparently warns that many pre-mapped topics return safety warnings, setting expectations about real tradeability.

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 organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and each sentence adds value. It is longer than average, but this is justified given the tool's complexity. It is front-loaded with the core purpose and then expands into technical details, making it effective though slightly heavy.

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

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

With no output schema, the description carries the burden of explaining return values and edge cases. It covers the response structure (leg-by-leg prices, top_spreads_pp), safety fields and their conditions, temporal alignment semantics, and skipped counters. This is comprehensive and leaves no significant gaps for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that the `topic` parameter selects a pre-mapped macro shortcut and that `kalshi_event_ticker` and `polymarket_event_slug` override the mapped sides. This clarifies the interaction between parameters and the two modes, giving more than just the schema's per-parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the resource (two prediction markets), the operation (comparing spreads), and the distinguishing feature (venues price the same outcome differently). It also distinguishes itself from sibling tools by focusing on cross-venue spread rather than single-venue 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 explains two usage modes ('topic' for pre-mapped shortcuts, explicit ticker/slug for custom pairings) and provides a critical caveat: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' This tells the agent when the tool will not be useful. However, it does not explicitly mention alternatives or exclusions relative to sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds valuable beyond-annotation context: scoping to user identifier ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual retrieval/list behavior. It doesn't detail return format or missing-key behavior, so a 4 is appropriate.

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

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

Three sentences, each earning its place: core action in the first, use cases in the second, scoping and related tools in the third. Front-loaded 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?

Given the tool's low complexity (one optional parameter, no output schema, strong annotations), the description is complete: it states the purpose, typical usage, scoping, and relationships to remember/forget. An agent can accurately select and invoke this tool without further clarification.

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

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

The input schema fully documents the 'key' parameter with 100% coverage, including the instruction to omit it to list all keys. The description adds illustrative examples but no additional syntactic or semantic detail beyond what the schema already provides. Baseline 3 holds.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It names the resource (saved memories) and the action (retrieve/list), and explicitly references sibling tools (remember, forget), distinguishing it from them.

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

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

It provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It also names alternatives (remember to save, forget to delete), giving a clear workflow without needing to inspect other tool descriptions.

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 enriches the read-only annotation by describing the persistent feed, the evaluator's role, and the mark_read side effect that affects subsequent calls. It also mentions polling suitability, adding operational context beyond the annotations.

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

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

The description is concise and well-structured, with each sentence covering a distinct aspect: core function, return payload, filters, mark_read behavior, and alternative endpoint. There is no redundant or vague language.

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 fully covers return values, filtering, mark_read behavior, and polling suitability, which compensates well for the lack of an output schema. Remaining parameters are documented in the schema, making the overall guidance complete.

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

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

The schema already covers all five parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the effect of mark_read on the next call and highlighting the type and since filters, going beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the user's subscription feed and returns the most recent alerts with source, citation_uri, and raw payload. It is specific about the resource and action, but it does not explicitly distinguish itself from sibling tools like recent_changes.

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

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

The description gives clear context: it says polling works fine and notes an alternative GET endpoint for scripts/dashboards. However, it does not provide explicit exclusions or compare against sibling tools with overlapping functionality.

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; description adds dynamic behavior: fan-out to three sources, GDELT→GNews fallback on rate-limit/5xx, and USPTO soft-fail due to PatentsView sunset. Also explains return format (changes[] grouped by source, total_changes, citation URIs). 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?

Though single-paragraph, it's front-loaded with user-intent examples and packs essential details (federated sources, fallback behavior, input format, output shape, alternative tool) without fluff. Every sentence carries operational value.

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

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

Covers input formats, sources, fallback, output structure, and usage boundary vs entity_profile. With no output schema, it adequately describes the return value, making it self-sufficient for an agent.

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

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

Schema provides full descriptions for all three parameters (type enum, since format/examples, value ticker/CIK), so baseline 3 applies. Description adds broader context (e.g., that since drives the window across all sources) but doesn't add parameter-level syntax 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?

Description opens with natural-language query examples then clearly states it's a 'change feed for a company in the last N days/weeks/months in ONE parallel call', specifying sources (SEC EDGAR, GDELT/GNews, USPTO). It explicitly distinguishes from entity_profile ('Use entity_profile instead when you want the static profile').

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

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

Provides explicit when-to-use via query examples and an explicit alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This covers when-not and alternative in one phrase.

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

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

Beyond annotations (readOnlyHint false, idempotentHint true, destructiveHint false), the description adds key behavioral context: storage is scoped by identifier, anonymous sessions retain memory for 24 hours, while authenticated users get persistent memory. This is meaningful added context not present in 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?

Every sentence earns its place: what it does, when to use, storage format, persistence rules, and companion tools. No redundancy, and critical information is front-loaded.

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

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

For a simple 2-parameter tool with no output schema, the description fully covers purpose, usage, storage behavior, persistence, and integration with siblings. It is complete enough for an agent to decide when and how to use it.

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

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

Schema coverage is 100% with descriptive parameter names and examples. The description reinforces semantics by mentioning key-value pairs and giving example values (ticker, address, preference), adding slight extra 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 a specific verb ('Save data') and resource ('data the agent will need to reuse later'), distinguishing it from sibling tools like recall (retrieve) and forget (delete). It also mentions the key-value storage model, making the purpose unambiguous.

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

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

It explicitly says 'Use when you discover something worth carrying forward' and provides concrete examples. It also names companion tools ('Pair with recall to retrieve later, forget to delete'), giving direct alternative guidance.

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

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

Annotations already indicate safe read-only behavior, but the description adds critical behavioral context: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit reporting of unresolved identifiers, and cascading internal lookups. This goes far beyond the annotations and helps set expectations.

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

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

The description is long but information-dense, with every sentence adding value. It front-loads example queries and then covers supported types and edge cases. However, it is presented as a single block and could benefit from bullet points or clearer segmentation for readability.

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

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

With no output schema, the description adequately explains what the tool returns: identifiers labelled by source, explicitly stated unresolved identifiers, and specific outputs for company/drug types. It also covers fallback behavior, making the tool's behavior predictable.

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

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

Although schema coverage is 100%, the description enriches the `type` parameter by explaining the two supported types in detail and for `value` provides concrete examples (ticker, CIK, or name) and drug name examples. This adds practical meaning beyond the schema's brief descriptions.

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

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

The description clearly states its purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It lists concrete example queries and distinguishes itself from siblings by focusing on entity resolution across company and drug types.

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 to 'Use FIRST whenever you have a name but need an ID.' It also clarifies that it replaces 2-3 manual lookups, implying it is the primary entry point for identifier lookup, which distinguishes it from sibling tools like entity_profile.

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

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

The description discloses that it calls ai_visibility_check for each entity, ranks results by score, and returns a list including score, confidence, and signal density. This goes beyond the annotations (readOnly, idempotent) to explain internal behavior and output.

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

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

Three sentences, front-loaded with the main purpose, includes a concrete example and output summary, with no redundant content.

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

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

The description covers the tool's purpose, process, use case, and return format. It omits some operational details like external API usage for Anthropic, but those are captured in the schema parameters, so the description is sufficiently complete given the schema's richness.

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 covers all four parameters with descriptions (100% coverage). The tool description repeats the first-entry-as-subject concept already present in the schema's entity parameter description, adding no new parameter semantics.

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

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

The description clearly states a specific verb, resource, and scope: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from sibling ai_visibility_check by emphasizing multi-entity comparison and ranking, and from compare_entities by focusing on AI visibility specifically.

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 identifies a use case for competitive AI-marketing audits and provides an example query. It implies that ai_visibility_check is for single-entity probes while this tool aggregates them, though it doesn't explicitly exclude single-entity usage.

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

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

Annotations already indicate safe read-only, idempotent, open-world behavior. The description adds significant behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed reports timeouts. This goes beyond the annotations and sets accurate expectations.

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

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

The description is fairly long but every sentence serves a purpose: it front-loads the core purpose, then usage context, then output fields, then limitations. It could be tightened slightly by removing some redundancy, but for a complex multi-source tool it remains well-structured.

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

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

Given no output schema, the description compensates by enumerating the summary block fields (is_latest, license, published_at, etc.) and mentioning links and alternative versions. It also covers the NPM-only scope, partial failure behavior, and timeout characteristics, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces that the package parameter is an npm package name and that version defaults to latest, but these are already in the schema. It adds the ecosystem limitation (NPM only), but that's more a behavioral note than parameter semantics.

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

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

The description clearly identifies the tool as a composite 'should I add this npm package' check, combining deps.dev and bundlephobia data. This specific verb+resource focus uniquely distinguishes it from all sibling tools, none of which serve a similar purpose.

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

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

Explicitly states when to use: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also gives a clear fallback for non-NPM ecosystems (PyPI/Maven/Cargo/Go), effectively providing a when-not-to-use guideline for those cases.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the embedding model (BGE-base-en), chunking (500-char overlapping windows), truncation at 200K chars with a flag, and the return structure (passages with offsets and similarity scores). 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 information-dense but not bloated; it front-loads the core action, then provides use case, workflow, and implementation details. Every sentence earns its place.

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

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

For a tool without an output schema, the description adequately explains return values (top-N passages with offsets/scores), truncation behavior, and the recommended integration with ask_pipeworx_grounded. It leaves no critical gaps for a search operation.

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%, providing a baseline of 3. The description adds real-world examples for text and clarifies query as natural-language, which helps an agent understand parameter usage, but it largely reinforces schema details rather than adding entirely new semantics.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples (SEC 10-K, article). It distinguishes from sibling tools by emphasizing 'INSIDE' and pairing with ask_pipeworx_grounded as a complementary workflow.

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

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

Explicitly says when to use: when the record is too big for the prompt, and explains the benefit of saving context with offsets for verification. It also names the complementary tool ask_pipeworx_grounded, indicating a recommended workflow and alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context beyond annotations: title-scoped ranking, sort/filter capabilities, and the return fields. 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 three sentences, front-loaded with the core purpose, then expands into usage details and examples. No wasted words; each clause earns its place. The structure flows naturally from purpose to usage to returns.

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

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

Given the 8-parameter complexity and the presence of an output schema, the description is remarkably complete. It covers the main search behavior, sorting/filtering options, the title-scoped special case, and the return fields. It even includes concrete examples for common queries, making it easy for an agent to map natural language requests to parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by connecting parameters to real-use scenarios (e.g., 'most-cited papers on transformers' for sort=citations, 'papers on LLMs since 2024' for from_date), and it clarifies the distinction between title and query. This goes 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: 'Search academic papers, books, and datasets via Crossref.' It also immediately distinguishes a specialized title-scoped search mode, which sets it apart from sibling tools like get_work or get_journal that retrieve specific works.

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

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

Provides clear when-to-use guidance: 'For "search works titled X" / finding a SPECIFIC paper by its title, pass title.' It also gives concrete examples for sorting and filtering use cases. However, it does not explicitly mention alternative tools or when not to use this tool (e.g., when you already have a DOI, use get_work), so it stops short of full exclusion guidance.

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

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

Annotations already indicate non-readonly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: anonymous and BYO accounts cannot persist subscriptions, SMS requires phone verification and has a 10/day cap, and the feed channel is always on. These details help the agent anticipate side effects and prerequisites without contradicting the annotations.

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

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

The description is fairly long but carries dense, non-redundant information: purpose, return value, auth requirement, supported types with examples, and delivery options. It is front-loaded with the core action, though some tightening could make it easier to scan.

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

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

This is a complex tool with a nested delivery object and multiple type-specific parameter shapes. The description covers the main use cases, auth requirements, delivery channels, and return value, while leaving webhook signing and auto-disable details to the schema. Given the schema's richness, this is adequately complete, though it does not mention duplicate-subscription behavior (covered by the idempotent hint).

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

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

The input schema has 100% parameter coverage, with detailed descriptions for the type enum, params object, and delivery object. The description echoes much of this information (e.g., items:['5.02'], topic:'fed', series_id:'UNRATE') and adds the return of the subscription id, but it does not significantly extend what the schema already documents.

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 'Returns the new subscription id,' which clearly specifies the action and resource. This distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description explains the required context: a Pipeworx OAuth account is required, types and parameter examples are enumerated, and delivery channels are described. It also mentions pulling alerts via recent_alerts for the always-on feed. However, it does not explicitly contrast when to use subscribe versus listing or unsubscribing, so it stops short of full alternative guidance.

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive. The description adds valuable context beyond those flags, such as the return value structure (category-bucketed example questions with tool + argument shapes), the live catalog source, and the 'no arguments vs. topic' behavior, which together give a clear behavioral model.

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 minimal but front-loads natural language queries and the 'onboarding entry point' context. Every sentence contributes useful information—purpose, return content, argument behavior, and when to use it—so it is structured and purposeful, though slightly verbose for a single optional parameter.

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

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

With no output schema, the description fully explains what the tool returns (category-bucketed example questions with exact tool and argument shape), how to invoke it (with/without `topic`), and when to use it first. It also lists a wide range of covered categories, making the tool's scope unambiguous and complete for an onboarding assistant.

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 description already covers the `topic` parameter fully, including allowed values and the omission behavior. The tool description reinforces this with examples like 'finance', 'pharma', 'betting' and adds the 'full spread' nuance, but the marginal added meaning beyond the schema is minimal, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as the onboarding entry point for discovering what Pipeworx can do, with specific verbs like 'returns category-bucketed example questions' and lists concrete categories. It distinguishes itself from siblings by framing its role as the 'first' tool to use when unfamiliar with Pipeworx and explicitly references learning to call meta-tools.

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

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

The description gives explicit usage context ('Use this FIRST when you do not yet know what Pipeworx can do') and shows how to call it with or without the `topic` argument. It does not provide explicit when-not-to-use guidance or name a direct alternative, but the recommended first-use positioning makes the usage clear enough.

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

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

The description adds significant behavioral details beyond annotations: ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior ('The row is deactivated (not deleted) so its historical events stay available via recent_alerts'). This complements the annotations (idempotentHint, destructiveHint) with concrete consequences.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds value: the first states the operation, the second covers ownership and persistence behavior. No waste.

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

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

For a single-parameter tool with no output schema, the description covers the essential context: what it does, ownership restrictions, the deactivation mechanism, and the downstream effect on recent_alerts. This is complete for an agent to select and 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 already provides 100% coverage for the single parameter 'id' with a clear description ('Subscription id (uuid) returned by subscribe'). The tool description does not add additional parameter semantics beyond restating 'by id', which is redundant and yields the baseline score.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes itself from sibling tools like subscribe and list_subscriptions by focusing on cancellation, and the mention of 'recent_alerts' contextualizes the effect.

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

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

The description clearly implies when to use the tool (to cancel a subscription) and provides context about ownership enforcement. However, it does not explicitly state alternatives or when not to use it, though the sibling list makes it easy to infer.

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

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

The description discloses detailed behavioral traits beyond the annotations: the SEC EDGAR + XBRL fast path, the grounded pipeline fallback, the full verdict set, pipeworx:// citations, and the crucial distinction between could_not_verify (verification failed) and unsupported (no source). This adds significant context beyond the read-only/idempotent annotations.

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

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

The description is dense but logically organized: trigger phrases, usage, routing behavior, return values, and critical caveats. Every sentence adds value without redundancy, making it appropriately sized for the tool's complexity.

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

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

Given no output schema, the description fully covers return values (verdict types, citation, reasoning) and explains error behavior (could_not_verify vs unsupported). It also mentions that it replaces multiple sequential calls, providing full context for agent decision-making.

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 both parameters thoroughly described in the input schema. The description adds a small amount of behavioral context (e.g., exact percent-delta math, tolerance cap), but the schema already carries the semantic load, so this is at the acceptable baseline.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, with specific trigger phrases and a clear verb+resource ('verify the claim that…'). It distinguishes itself as a consolidated alternative to multi-step lookups, making the purpose unambiguous.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two routing paths for company-financial vs. other claims. However, it does not name specific sibling tools or state explicit exclusion criteria, so it misses the highest bar for alternative guidance.

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