Legiscan

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

Annotations already declare read-only and idempotent. Description adds that it probes LLMs, returns per-model results, and requires a key for Anthropic. No contradictions.

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

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

Four sentences, front-loaded with main action, then defaults, returns, and use cases. No wasted words.

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

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

Covers all parameters, return format, and use cases. No output schema needed given the description.

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

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

Schema coverage is 100%, but description adds context: default model is Workers AI, _apiKey is BYO and billed separately. Enhances understanding 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?

Clearly states the action (probe), resource (LLMs), and output (visibility score 0-100). Distinguishes from siblings by focusing on AI visibility audits.

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 mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and provides model selection guidance (default vs. Anthropic w/ key). Could mention when not to use or differentiate from similar 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 establish that the tool is read-only, open-world, idempotent, and non-destructive. The description adds useful behavioral detail: dynamic routing across 5,908 tools, automatic argument filling, stable citation URIs, and automatic inclusion of sources. There is no contradiction with 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 much longer than needed for a one-parameter tool and repeats itself: 'even if web search could also answer' appears twice, and similar examples like 'current US unemployment rate' and 'Apple's latest 10-K' are duplicated. It is front-loaded with the key preference, but the redundancy undercuts conciseness.

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

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

For a single natural-language parameter and no output schema, the description covers the key context: when to use, what domains it handles, that citations and sources are returned automatically, and which sibling tools to use for other workflows. It is complete enough for selection and invocation, though it omits caveats about latency, failure modes, or the beta/grounded variants.

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%: every parameter is documented as an alias for the natural-language question. The description reinforces this with usage examples but adds no parameter-level meaning beyond what the schema already provides, so the schema does the heavy lifting.

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

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

The description clearly states that ask_pipeworx answers factual questions by routing them to one of 5,908 underlying tools and returning structured answers with pipeworx:// citation URIs. It does not, however, explain how ask_pipeworx differs from the sibling tools ask_pipeworx_beta and ask_pipeworx_grounded, so differentiation is incomplete.

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 preference over web search, lists trigger phrases and domains, provides concrete examples, and names alternatives: deep_research for deep research, recall for follow-up questions, and compare_entities for entity comparisons. It also instructs the agent not to append external search results because sources are already included.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the experimental edge, the possibility of live routing improvements, the current inactive candidate state, and the fact that this is a full working router. This adds useful behavioral context that the agent needs to manage 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 longer than strictly necessary but front-loads the essential facts: beta, identical to stable, candidate routing, current status, and usage instruction. Each sentence earns its place, though some redundancy exists around being a full router and having the same tools/arguments/shape.

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 explains what the tool is, its current behavioral state (no active candidate), how to use it, and how it compares to the stable sibling. Even without an output schema, it notes the response shape is identical to ask_pipeworx, making the tool fully actionable.

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

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

The input schema covers all six parameters with descriptions and 100% coverage. The description adds no new parameter meaning beyond saying 'same arguments' as ask_pipeworx, which is consistent but not additive. 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 identifies this as the beta version of ask_pipeworx, a universal router with identical tools, arguments, and response shape, but with candidate routing improvements. It distinguishes itself from the stable sibling by its experimental nature and explicitly states it is a full working router, not a fallback.

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 notes that results are compared against the stable router. It also states that no candidate is currently active, so it matches ask_pipeworx exactly, giving clear guidance on when and how to use it relative to the sibling.

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

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

Beyond annotations, the description discloses critical behavioral traits: extraction uses ONLY the tool result, returns verbatim evidence, returns a structured refusal with enumerated refusal reasons when data doesn't answer, and costs an extra LLM call. These details go well beyond the readOnly/openWorld/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 every sentence earns its place: it explains the mechanism, return contract, refusal behavior, use cases, and cost tradeoff. Key differentiators are front-loaded, and no filler or redundant restating of the schema is present.

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 a simple single-question parameter and no output schema, the description fully specifies the expected return shape, refusal reasons, intent, and tradeoff versus the sibling. An agent has enough information to select and invoke the tool correctly without further inference.

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 every parameter already documented as an alias for the natural-language question. The description adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, with specific verbs and a defined resource: extracting grounded answers from tool results. It also differentiates itself from sibling ask_pipeworx by emphasizing evidence-based extraction and refusal behavior.

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

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

The description explicitly says to use this tool when answers will be quoted, cited, or acted on and the agent must not invent facts, listing high-stakes domains. It also explicitly recommends preferring ask_pipeworx for casual lookups due to the extra LLM call, giving clear when-to-use and when-not-to-use guidance.

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

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

The description richly details behavioral traits beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It explains the fan-out process, classifiers, response shapes, resolver contract (including confidence levels and alternatives), parent event extraction, news fallback handling, safety short-circuits, closed market handling, wide-spread liquidity notes, and resolution-rule risk. No contradiction with annotations is present.

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 comprehensive but lengthy. It is well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), which aids readability. However, it could be more concise by prioritizing the most essential information for agent selection.

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 complexity of the tool (3 parameters, no output schema), the description provides exhaustive coverage: purpose, usage, input formats, detailed behavior, return values, edge cases, and safety considerations. It fully compensates for the lack of an output schema.

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

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

Schema coverage is 100%, and the input schema already fully describes the parameters (market, depth, include_raw) with the same information. The description does not add new meaning or constraints beyond what is in the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and includes examples of input types. This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_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 explicitly lists usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context, though it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds rich context: for companies it pulls revenue, net income, cash, debt from SEC EDGAR/XBRL with correct fiscal year handling; for drugs it pulls FAERS, FDA approvals, trial counts. It explains sorting by primary metric and returns paired data with citation URIs.

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

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

The description is front-loaded with example queries and concisely states purpose, data sources, sorting, and efficiency gains. Every sentence is informative, but could be slightly more structured. Still appropriate for the complexity.

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

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

Despite no output schema, the description explains return format (paired data + citation URIs), data sources, sorting, and parameter constraints. It fully covers what an agent needs 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: explains that 'type' determines data source (company vs drug) and that 'values' should be tickers/CIKs for companies or drug names for drugs, with examples. This is beyond the schema's enum and array description.

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

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

The description explicitly states the tool performs side-by-side comparison of 2-5 companies or drugs in a single parallel call, with clear examples like 'compare X and Y'. It distinguishes itself from sibling tools by saying 'ALWAYS PREFER over sequential single-pack lookups' and mentions it replaces 8-15 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?

The description strongly advises using this tool for comparing multiple entities over sequential lookups, but does not explicitly mention when not to use it (e.g., for single entity lookups). It provides clear context 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?

Even though annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, the description adds substantial behavioral context: account requirements, parallel decomposition into 5,908 tools, findings packet structure with gaps[], contradiction scanning, citation URI fetchability, semantic excerpting, and expected latency. Nothing contradicts 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 highly informative but overlong and somewhat disorganized. It mixes account requirements, usage guidelines, depth mechanics, and return details in a dense paragraph, plus a malformed `depth:"thorough"` string. Every point is valuable, but the structure would benefit from clearer separation and more scannable formatting.

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

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

With no output schema, the description thoroughly explains the return value shape: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers depth-specific behavior, latency, and what happens when the topic is not in the structured catalog, leaving no critical information for the agent to infer.

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

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

The input schema already fully documents both parameters, so the baseline is 3. The description earns a 4 by adding critical semantics not present in the schema: 'thorough' requires a paid plan, 'standard' and 'thorough' enable contradiction detection, and depth variants differ in hop behavior and gap recovery.

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 over Pipeworx's 1540 structured data sources in a single call, explicitly calling out that it is NOT open-web search. It also contrasts with ask_pipeworx for single lookups, making the purpose and distinction from siblings unmistakable.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also warns against confusing it with open-web search, giving an agent clear routing criteria.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it 'returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This provides useful behavioral context beyond annotations, without contradiction.

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

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

The description is moderately sized, front-loaded with the main purpose, then lists example use cases and return details. Every sentence adds value, though it could be slightly more concise. It avoids unnecessary information.

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

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

Given there is no output schema, the description adequately explains what the tool returns (names, descriptions, schemas) and the use context. It covers the key aspects for a discovery tool, including when to use it and the richness of results.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the 'query' parameter accepts multiple aliases (q, task, search, description) and provides example values, which helps the agent understand how to use it effectively.

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: 'Find tools by describing the data or task.' It provides specific examples of use cases (SEC filings, FDA drugs, etc.) and distinguishes it from sibling tools, which are more specific. The verb 'discover' plus resource 'tools' is precise.

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

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

The description explicitly advises to 'Call this FIRST when you have many tools available.' This gives clear when-to-use guidance. It doesn't explicitly mention when not to use it, but the context implies it's for browsing/searching rather than direct calls to known 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 readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context beyond those hints: the parallel fan-out across SEC EDGAR, XBRL, USPTO, USAspending, Purple Book, DOL LCA, news, and GLEIF; the `sources_used`/`sources_failed` contract where an empty section is a real 'no data' rather than a bug; and the expectation that small-molecule-only companies show no fda_products. This prevents an agent from misreporting healthy empty results as failures.

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

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

The description is a very dense single paragraph, but nearly every clause is load-bearing: routing guidance, source list, return shape, empty-result semantics, input formats, and edge cases. The core purpose and ALWAYS PREFER rule are front-loaded. It loses a point for being a wall of text with some redundancy — the interchangeable type behavior restates schema content, and paragraph breaks would improve scanability for an agent.

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

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

With no output schema, the description carries the full burden of documenting return values, and it does so thoroughly: cik, company_name, resolved_from/to, recent_filings with URIs, fundamentals fields, patents, contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. All foreseeable edge cases for a multi-source entity tool are covered, making the description effectively 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 description coverage is 100%, so the schema already documents both parameters with examples ('AAPL', '0000320193', 'Moderna'). The description adds genuine value beyond the schema by explaining name resolution via SEC EDGAR company-name match and the resolved:false behavior for private companies, which affects how an agent interprets the output rather than just the input format.

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: 'full cross-source profile of a US public company in ONE parallel call,' backed by concrete example intents ('Tell me about X', 'research Acme', 'brief me on Tesla'). It distinguishes from siblings by explicitly preferring this over 'chaining single-pack SEC/XBRL/news lookups for a holistic view,' so an agent can route correctly without opening schemas.

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

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

Gives an explicit preference rule with a condition: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also enumerates accepted input shapes (ticker, zero-padded CIK, company name) and the edge-case path (private company returns resolved:false with a notes line), leaving no ambiguity about when and how to invoke.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds use-case context but does not elaborate on behavioral nuances beyond what annotations state, so it adds moderate value.

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: first states the action, second gives usage guidance. No redundant words; highly efficient and front-loaded.

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

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

For a simple tool with one parameter, clear annotations, and no output schema, the description covers purpose and usage adequately. It could mention idempotency but annotations already cover 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?

With 100% schema coverage, the parameter 'key' is already documented as 'Memory key to delete.' The description does not add new semantic meaning, so baseline 3 is warranted.

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

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

The description states 'Delete a previously stored memory by key,' which is a specific verb-resource pair. It explicitly pairs with sibling tools 'remember' and 'recall,' distinguishing it as the deletion counterpart.

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 when-to-use scenarios: 'context is stale, task is done, or clear sensitive data.' It suggests pairing with remember and recall, but lacks explicit when-not-to-use advice, so a 4 is 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 convey safe, read-only, idempotent behavior. The description adds rich behavioral detail: 'fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format.' It also specifies output as a single text blob. No contradictions.

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

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

The description is compact (two sentences plus a bulleted use-case list). It front-loads the core action and output format. Minor improvement: could list parameters more explicitly, but overall efficient.

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

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

Given no output schema, the description fully covers the output format ('standard llms.txt markdown format', 'single text blob'). It also explains the process and gives use-case context, making it complete for a simple read-only tool.

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

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

Schema description coverage is 100%, so the description does not need to add parameter details. It merely rephrases the url and max_links purpose without deeper semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to generate a llms.txt file for any URL for AI crawlers. It uses specific verbs ('generate', 'fetches', 'extracts', 'emits') and distinguishes itself from general AI visibility tools by focusing on the llms.txt standard.

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

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

The description explicitly lists three use cases (getting client's site indexed, drafting for own project, auditing competitor). It does not provide when-not-to-use or compare with siblings like 'scan_competitor_ai_presence', but the context is clear enough for an agent to select it appropriately.

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 all true, and destructiveHint false, so the safety profile is clear. The description adds behavioral detail about the return content (status, sponsors, subjects, links) beyond annotations, which is helpful.

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

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

Two sentences plus an example – extremely concise. First sentence states purpose, second gives usage guidance. Front-loaded and no wasted words.

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

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

Given the simple tool (one required param, no output schema), the description covers purpose, input source, example, and return fields. Annotations cover safety. No gaps remain.

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

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

Input schema covers both params with detailed descriptions (bill_id source, API key optional). Schema coverage is 100%. The description repeats the bill_id usage but does not add new semantic meaning beyond what the schema provides.

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

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

The description clearly states 'Get the full detail for a single US legislative bill' with specific verb and resource. It lists included fields (status, sponsors, subjects, links) and differentiates from sibling tool search_bills by mentioning using bill_id from search_bills.

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

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

The description explicitly says 'Use the bill_id returned by search_bills' which provides clear context for when to use this tool. It includes an example call. While it doesn't mention when not to use or list alternatives, the guidance is straightforward and sufficient.

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, and non-destructive. The description adds context about output (start/end years, session IDs) and provides an example. This supplements the annotations without contradicting them.

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

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

The description is two sentences plus an example, with no unnecessary words. It efficiently conveys purpose, usage context, and a concrete example. Every part 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?

The tool has low complexity with one required parameter and no output schema. The description covers what is returned (start/end years, session IDs). It lacks details like sorting or data limits, but for this simple list tool it is sufficient.

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

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

Schema coverage is 100%, with both parameters (state, _apiKey) described in the schema. The description adds little beyond the schema, only showing an example with state. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists legislative sessions for a US state, including regular and special, with start/end years and session IDs. It uses a specific verb ('List') and resource ('legislative sessions'), and distinguishes itself from sibling tools that handle bills or other entities.

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 suggests using this tool to 'scope which session to track bills in', providing clear context. It does not explicitly state when not to use or mention alternatives, but the implied use case is adequate.

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 value by specifying the return fields and the effect of the include_inactive parameter, which is beyond what annotations provide.

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

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

The description is two sentences: the first explains functionality and output, the second gives usage guidance. It is concise, front-loaded, and 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?

Despite the absence of an output schema, the description lists the return fields. Combined with the rich annotations and single documented parameter, the description provides complete context for the simple list tool.

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

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

Schema description coverage is 100% for the single parameter. The description restates the parameter's purpose but does not add new semantic meaning beyond the schema. However, it provides usage context, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, etc.). It uses a specific verb-resource pair and distinguishes from siblings 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 explicitly advises when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel,' providing clear context and exclusion of alternatives.

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

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

The annotations are all false and offer minimal safety information, so the description carries the full transparency burden. It discloses operational traits such as rate limiting ('Rate-limited to 5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), the claim_token workflow for follow-up, and the impact on roadmap ('signal directly affects roadmap'). These details go well beyond the structured annotations.

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

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

The description is lengthy but every sentence is purposeful: scope, exclusions, token workflow, rate limits, and roadmap impact all are necessary. It is front-loaded with the core purpose, though the stream-of-thought structure could be more organized. There is no fluff, but a slightly more structured presentation would make it a 5.

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

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

With four optional parameters, no output schema, and sparse annotations, the description compensates fully. It covers the tool's scope boundaries, feedback categories, claim_token usage, rate limits, quota exemption, and operational details like daily digest reviews. This leaves no significant gaps for 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?

Schema description coverage is 100%, so the baseline is 3. The description enriches the schema by explaining the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by advising users to describe issues 'in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' adding meaningful usage nuance to the message and context parameters.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from sibling tools by restricting scope to 'tools served by this Pipeworx connection' and enumerates feedback categories (bug, feature, data_gap, praise), making its purpose unmistakable.

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

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

The description provides explicit when-to-use guidance for each category ('Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog...') and an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also offers a clear heuristic for identifying Pipeworx tools, leaving no ambiguity about when to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe. The description adds valuable context: self-aggregating signal from CF analytics-engine, no PII, cached 5min-1h depending on window. This goes 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, well-structured with bullet points for use cases. Every sentence adds value, and the length is appropriate.

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

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

Despite no output schema, the description explains what is returned: top tools, top packs, total call volume. It also mentions caching. For a trending tool, this provides sufficient context for the 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 description coverage is 100% with well-described enum. The description adds meaning by explaining the trade-off between windows: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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 returns: top tools, top packs, and total call volume over a recent window. The verb 'returns' and resource 'trending' are specific and distinguish it from siblings like 'discover_tools' or 'ask_pipeworx'.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming popular tool, aligning use case). It provides clear context for when to use the tool, though it does not explicitly state when not to use it or mention alternatives among siblings.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds extensive behavioral detail: explains monotonicity checks, partition-sum, Jaccard similarity filter, placeholder filtering, and fill check with CLOB depth. 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 verbose but well-structured. Front-loaded with overall purpose, then details each mode and algorithms. Every sentence provides value, though some technical details could be condensed. Still efficient for a complex tool.

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

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

Given no output schema, the description fully explains the response structure (opportunities[], partition_check, fill_check) and edge cases. Covers input, behavior, filtering, and trade advisories. No gaps 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 covers 100% of parameters with descriptions. The description adds significant context: examples of slugs, the checks performed in each mode, and the cross-event behavior. Goes beyond the schema's minimal 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and differentiates from sibling tools like polymarket_fill_risk. The verb 'find' and resource 'arbitrage opportunities' are specific.

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

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

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Includes a recommendation and warns against trading when edge is non-positive. Mentions alternative tool for custom sizing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond by detailing caching behavior (1h at KV level keyed on all knobs), response structure including diagnostics for empty segments, and the fact that the tool does not mutate state. No contradiction.

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

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

The description is lengthy but well-structured: purpose first, then model families, response shape, configuration knobs, and diagnostics. Every sentence carries distinct information. Could be slightly more compact, but it earns a 4 for organization and efficiency.

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 9 parameters, no output schema, and complex response structure, the description is remarkably complete. It explains return segments (by_segment with three groups), diagnostics for debugging empty results, caching policy, and special handling for Fed bets. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial value by explaining real-world implications (e.g., slippage context, Polymarket fee structure, why min_kelly and min_partition_leg_kelly behave differently for partition arbs). This extra context warrants a 4.

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

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

Description starts with a clear verb-resource pair ('Scan top Polymarket markets') and states the core output: opportunities where Pipeworx data disagrees with market price. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by framing this as a daily discovery scan.

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 targets the use case 'what should I bet on today' and mentions that agents avoid paging hundreds of markets. It details filters (knobs) but does not explicitly contrast with siblings or state when not to use. Given the clear context, a 4 is 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?

The description discloses behavioral traits beyond annotations, such as snapshot gaps meaning no scan, TTL of 60 days, decay from daily closes (not intraday), and the structure of response. No contradiction with annotations.

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

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

The description is well-structured with front-loaded purpose and detailed output fields. While a bit verbose, each sentence adds value, and there is no redundancy.

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

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

Despite no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and limitations, making it fully actionable for an AI 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 parameter descriptions. The description adds context like default and max values for days, default window, and explains that snapshots are from polymarket_edges, enhancing understanding.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge longevity. It distinguishes itself from siblings like polymarket_edges by focusing on time-series analysis.

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 when to use this tool (to assess edge persistence before trading) by contrasting fresh vs. old edges. It also mentions limitations but does not explicitly list alternatives or when not to use.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral context: it mentions walking the ladder, returning detailed fill data (top_of_book, vwap_fill_price, slippage_pp, etc.), and warning about forced directional risk. No contradictions.

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

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

The description is lengthy but every sentence serves a purpose, covering both modes and their nuances. It front-loads the core purpose but could benefit from bullet points for the return fields and modes. Given the complexity and the need to explain two modes, it is appropriately sized and structured.

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

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

No output schema is provided, so the description must fully explain return values. It does so comprehensively for both modes: lists all returned fields (e.g., top_of_book, verdict, capture_ratio, thin_legs) and explains edge cases (partial fills leading to directional risk). The description is complete given the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining default values (size_usd=1000, side auto for basket), clarifying how size_usd is interpreted differently for single vs basket (max spend vs settlement notional), and noting the automatic side selection based on partition sum. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between two modes (single-market and basket), using specific verbs like 'check', 'walk the ladder', and 'return' for each. This sets it apart from sibling tools like polymarket_arbitrage and polymarket_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?

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.' It explains why partial fills can convert an arb into an unhedged position, and clarifies the requirement of either `market` or `event` parameter. No exclusion of alternatives is needed as the tool is a prerequisite for specific signals.

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

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

Even though annotations already mark this as read-only, idempotent, and non-destructive, the description adds extensive behavioral disclosures: compatibility warnings/codes may be non-empty, temporal_alignment null means unknown rather than aligned, Kalshi fees are not modeled so spreads are gross, and skipped/unclassified comparisons are exposed. It clearly explains what the tool does and does not guarantee.

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: purpose first, then modes, response shape, safety fields, limitations, and caveats. It is front-loaded and organized, though some points, especially temporal-alignment semantics, are repeated in slightly different forms. Each section earns its place given the tool's complexity.

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

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

There is no output schema, so the description correctly carries the burden of explaining return values: per-venue leg prices, top_spreads_pp, compatibility fields, skipped counts, temporal alignment, and fee disclosure. Combined with the parameter modes and safety caveats, an agent has enough context to call and interpret 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 coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics by explaining how `topic` selects pre-mapped shortcuts, how explicit ticker/slug overrides replace the topic-mapped side, and that both modes run identical matching logic. This goes 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 computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific verbs and a clear resource. It does not explicitly name or differentiate against sibling tools like polymarket_arbitrage, but its scope is specific enough that an agent can infer its unique role.

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

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

The description gives explicit usage context: two modes (`topic` shortcuts vs explicit ticker/slug pairings), how overrides work, and that both modes run the same matcher. It also warns that most pre-mapped topics may return compatibility warnings and are not necessarily tradeable, but it does not explicitly state when to prefer alternative 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 readOnly, idempotent, non-destructive. Description adds listing behavior and scoping. Could mention error handling for missing key, but overall good.

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

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

Two sentences, front-loaded with core action, no redundant information. Efficient and clear.

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

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

For a simple read tool with good annotations, the description covers purpose, usage, scoping, and pairing with siblings. No gaps.

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

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

Schema coverage is 100% with clear param description. Description reinforces and adds the behavior of omitting key to list all keys, providing full context.

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

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

The description clearly states it retrieves a value by key or lists all keys if omitted, with specific verb and resource. It distinguishes from siblings 'remember' and 'forget'.

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

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

Provides explicit when-to-use: 'look up context the agent stored earlier', and scoping details. Does not explicitly say when not to use, but the purpose is clear enough 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 that setting mark_read:true modifies event read status, which is a write operation. However, annotations declare readOnlyHint=true, creating a direct contradiction. Per rules, a contradiction scores 1.

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 concise (about 150 words) and front-loads the main purpose. It efficiently covers key points, though it could be slightly more streamlined without losing clarity.

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 5 optional parameters and no output schema, the description fully explains return fields, filtering options, side effects of mark_read, polling suitability, and an alternative access method. This provides a comprehensive understanding for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical meaning beyond schema, including examples (e.g., type 'sec_8k'), clarifies behavior of mark_read and since, and explains the effect on subsequent calls.

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 'Pull fired events from your subscription feed,' specifying the action (pull) and resource (alerts). It differentiates from sibling tools like list_subscriptions by focusing on retrieving alert data rather than managing subscriptions.

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

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

The description includes context such as 'Polls work fine' and mentions an alternative access method (GET endpoint), providing guidance on when to use the tool. However, it lacks explicit exclusions or when-not-to-use instructions compared to 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 safe read-only, idempotent behavior. The description adds significant behavioral details: fans out to multiple sources in parallel, fallback from GDELT to GNews, soft-fail for USPTO patents, and return structure including citation URIs. No contradiction with annotations.

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

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

The description is relatively long but front-loaded with common use cases. It packs a lot of necessary information into a few sentences. While it could be slightly tighter, it avoids redundancy and each sentence adds value.

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

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

Given the tool's complexity (multiple data sources, parameter options, fallback behavior) and the absence of an output schema, the description covers all critical aspects: sources, date handling, return format, and alternative tool. It is complete enough for an agent to use 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 baseline is 3. The description adds value beyond schema by explaining the 'since' parameter accepts both ISO dates and relative shorthand with examples ('7d', '30d', '3m', '1y'), and recommends '30d' or '1m' for typical monitoring. It also clarifies that 'value' can be a ticker or zero-padded CIK.

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 starts with representative queries and states the tool provides a change feed for a company, covering SEC, news, and patents. It explicitly distinguishes itself from the sibling tool entity_profile, which focuses on static profiles. The verb 'change feed' and resource 'company' are specific and 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 provides explicit when-to-use scenarios ('What's new with X', 'latest on Y') and when-not-to-use (use entity_profile instead for static profile). It also gives alternatives and usage context, such as the fallback behavior between GDELT and GNews.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. Description adds lifecycle details: persistent for authenticated users, 24-hour retention for anonymous, and scoping by identifier. No contradictions.

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

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

Three sentences, front-loaded with purpose, each sentence adds essential information. No wasted words.

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

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

Given 2 params, no output schema, and annotations, the description fully covers when and how to use, scoping, persistence, and pairing with siblings. Complete for a storage tool.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by exemplifying key naming conventions and value type, exceeding the baseline of 3.

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

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

Clearly states the tool saves data for reuse across conversations/sessions, with concrete examples. Distinguishes from sibling tools recall and forget.

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

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

Explicitly advises when to use ('discover something worth carrying forward') and pairs with recall/forget, providing clear 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?

Annotations already declare readOnly/openWorld/idempotent, so the safety profile is covered. The description adds substantial behavioral context: it explains the internal cascade across multiple endpoints, that ambiguous matches return `figi_candidates` rather than asserting a single result, that unresolved identifiers are listed explicitly under `unresolved`, and that enrichment degrades gracefully if GLEIF/OpenFIGI is unavailable. This is far beyond the annotation baseline.

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 packs a lot of necessary detail for a complex multi-entity resolver. It is front-loaded with user-intent examples and a clear purpose, then organized by entity type, followed by degradation behavior and a closing note about internal efficiency. While slightly verbose, every segment earns its place given the tool's complexity.

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

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

With no output schema, the description must convey return semantics, and it does: it lists all returned identifiers, explains labeling by source, describes the `unresolved` section, and covers the ambiguous-match scenario. It also explains how ISIN maps to legal entities. This gives the agent a thorough understanding of what to expect, which is especially important for a tool that replaces multiple manual lookups.

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

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

Schema description coverage is 100%, but the description adds critical semantics not present in the schema: for the `value` parameter it details acceptable inputs for company (ticker, CIK, name, or ISIN) and drug (brand or generic), and it warns against including trailing security-class words for bond issues. These nuances directly improve the agent's ability to construct valid calls.

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 user queries and then states a precise purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly covers the two supported entity types (company, drug) and lists the specific identifiers returned (CIK, ticker, LEI, FIGI, RxCUI). This clearly distinguishes it from sibling tools like entity_profile or compare_entities, which serve different purposes.

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

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

The description gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also provides specific usage nuances, such as for bonds: 'pass the ISSUER exactly as printed... never the question's full noun phrase.' This goes beyond a general when-to-use and equips the agent with actionable selection criteria, including how to format input correctly.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds specifics: it probes with ai_visibility_check, ranks by score, returns score/confidence/signal density, and treats the first entity as the subject. This provides valuable behavioral context beyond annotations.

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

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

The description is three concise sentences that front-load the main function, followed by method, use case, and output format. Every sentence earns its place with no wasted words.

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

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

The description adequately covers input, process, and output format, referencing the underlying ai_visibility_check. However, it could be more complete by specifying ordering direction (e.g., descending score) and error handling behavior.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by specifying that the first entity is treated as the 'subject' for narrative purposes, which is not in the schema description for the entities parameter.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side', identifying the specific verb 'compare' and resource 'AI visibility'. It differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison), making it distinct.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and implies when to use this tool over the sibling ai_visibility_check for single entities. However, it lacks explicit 'when not to use' guidance.

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

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

Beyond annotations (readOnly, idempotent), description discloses composite call behavior, partial failure degradation, and bundlephobia's first measurement delay (5-30s). It adds valuable context about sources_failed reporting, which annotations do not cover. No contradictions.

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

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

Description is front-loaded with main purpose and use cases, then details return structure, ecosystem limitations, and failure behavior. All sentences are informative, though slightly verbose. Could tighten but structure is logical and effective.

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

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

Despite no output schema, description fully explains return format (summary block, advisories, links, alternatives) and handles complexity like partial failures and performance delays. Adequate for agent to understand tool capabilities and expectations.

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

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

Schema covers both parameters with descriptions (package name, version with default). Description adds minor context (scoped packages accepted, version defaults to latest), but schema coverage is 100%, so baseline of 3 is appropriate. No significant added meaning 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 clearly states the tool is a composite check for npm packages using deps.dev and bundlephobia, specifying the exact resource and action. It implicitly distinguishes from sibling tools by its unique focus on npm dependency analysis, setting it apart from other research tools.

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

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

Description explicitly provides when to use ('is X safe / popular / small', 'what does adding lodash cost me') and when not to use ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), offering clear context and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context: it returns specific fields, supports nationwide or one-state search, and provides an example. It doesn't cover rate limits or edge cases, but the annotation coverage lowers the bar.

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 plus a concrete example, front-loaded with the main purpose. Every sentence earns its place, with no redundancy or filler.

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

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

Given the simple schema and rich annotations, the description is complete: it explains the tool's scope, output shape, integration with get_bill, and provides a usage example. No output schema exists, but the return values are explicitly named.

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's example reinforces parameter usage but does not add semantic meaning beyond what the schema already provides. No penalty, but no extra credit.

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 ('Full-text search US state (and federal) legislation') and clearly states the scope (one state or ALL) and the output (matching bills with key fields and a bill_id). It also distinguishes itself from siblings by mentioning the pass-off to get_bill, making the purpose unmistakable.

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

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

The description gives clear usage context: searching for bills about a topic, optionally limited to a state, and explains that results include a bill_id that can be passed to get_bill. It implies a workflow but does not explicitly state when not to use this tool or name alternatives beyond get_bill.

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

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

The description adds significant behavioral context beyond what annotations provide: it specifies the embedding model (BGE-base-en), similarity metric (cosine over 500-char overlapping windows), character cap (200K chars with truncation and flagging), and output details (offsets and similarity scores). This fully informs the agent of the tool's internal 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 concise, structured with a clear opening statement, use case, pairing advice, and technical details. Every sentence adds value without redundancy. It is front-loaded with the primary purpose.

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

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

Despite the absence of an output schema, the description fully explains the return format (passages with character offsets and similarity scores). It also covers edge cases (truncation), technical details (embedding model, window size), and integration with sibling tools, making it complete for an agent to select and invoke the tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The tool description adds value by providing example queries for the 'query' parameter and clarifying the character cap for 'text'. The 'limit' parameter defaults are also given. This extra context merits a score above the baseline of 3.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifies the input (text and query), and the output (top-N passages with offsets and scores). It distinguishes itself from siblings by explicitly mentioning its pairing with ask_pipeworx_grounded for grounding over relevant passages.

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

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

The description explicitly states when to use this tool: 'Use when the record is too big to cram into the prompt.' It also explains the benefit (saves context, returns only relevant passages) and mentions the character cap and truncation behavior, providing clear guidance on its appropriate use.

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

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

The description adds significant behavioral context beyond annotations: it notes the requirement for a persistent account, mentions SMS rate limits, webhook auto-disable after failures, and that the webhook secret is returned only once. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

The description is well-organized into logical sections (type, params, delivery) and includes examples. Every sentence adds value, though it is slightly verbose. It could be tightened without losing clarity.

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 subscription types, nested delivery options, multiple required fields), the description covers all key aspects: requirements, constraints, examples, and side effects. No output schema exists, but the description explains return values (subscription id, webhook secret).

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 adds rich detail for each type parameter (e.g., sec_8k items codes, fred_series series_id) and delivery options (SMS verification, webhook HMAC signing). This provides crucial usage guidance 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 action ('creates a proactive monitoring subscription') and the resource ('live-data event stream'). It distinguishes from sibling tools like list_subscriptions and unsubscribe by specifying creation and subscription 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 provides explicit prerequisites (Pipeworx OAuth account, not for anonymous/BYO) and explains when to use specific subscription types with examples. It lacks explicit when-not-to-use guidance but strongly implies appropriate contexts.

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 behavior. Description further explains it returns category-bucketed example questions with exact tool+argument shapes, using the live catalog. No contradictions.

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

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

Description is relatively long but well-structured, front-loaded with the canonical question, and uses bullet-point-like examples. Slightly verbose but justified by the informational density.

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

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

Though no output schema, description thoroughly explains the return format (category-bucketed example questions). Parameter is fully covered. Adequate for a discovery tool with no nested objects.

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

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

Schema coverage is 100%. Description adds meaning by listing exact topic values and explaining the effect of omitting vs specifying a topic, which goes 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?

Description explicitly states the tool is the onboarding entry point for a new agent, returns category-bucketed example questions, and distinguishes from siblings by focusing on 'what can I ask?' rather than executing queries.

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?

Clear guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains when to pass the optional topic parameter.

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 (destructiveHint=false), the description explains that the row is deactivated not deleted, and historical events remain available via recent_alerts. This adds valuable behavioral context.

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

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

Three short sentences convey all necessary information without redundancy. Every sentence adds value and the key action 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?

Given the tool's simplicity (single parameter, no output schema), the description is complete. It covers purpose, ownership, behavior, and side effects, leaving no unanswered questions for an AI agent.

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

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

The input schema covers the single parameter 'id' with a description. The tool description does not add further details about the parameter beyond what the schema provides, so it meets the baseline for 100% 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 begins with 'Cancel a subscription by id', clearly stating the verb and resource. It further distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement.

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 ownership enforcement, which guides when to use this tool (only for own subscriptions). It does not explicitly mention alternatives, but the context is clear. A slight improvement could be adding a note about when not to use it.

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

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

The description adds rich behavioral context beyond the annotations: it explains that could_not_verify means the check did not happen and must not be treated as evidence, clarifies unsupported means no source covers it, and discloses routing logic (SEC EDGAR vs grounded pipeline). This is significant operational detail that annotations do not provide.

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

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

The description is long but well-structured, moving from trigger phrases to purpose, routing, return values, and critical caveats. Every sentence carries useful information, though the opening list of examples is slightly verbose. The caveats about could_not_verify and unsupported are essential and not redundant.

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

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

With no output schema, the description fully explains return values (verdict list, actual value with citation, reasoning) and error semantics (verification_error with stage and detail). It covers routing, usage, failure modes, and the fact it replaces multiple sequential calls. For a tool with two simple parameters, this is comprehensively 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?

Both parameters are fully described in the schema (100% coverage), so the baseline is 3. The description adds extra meaning: tolerance_pct can be set to 1–2 for hallucination detection, default is implied by wording capped at 5, and the claim parameter's routing behavior is clarified. This elevates it above baseline.

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

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

The description opens with a list of natural-language triggers like 'fact check' and 'verify the claim that…', then states 'natural-language claim verification against authoritative sources' with a clear verb and resource. It distinguishes from siblings by focusing on verification with a verdict, which is a unique purpose among the listed tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing details for different claim types. It does not name alternative tools or explicit exclusion cases, but the context is clear enough to guide selection.

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