Library Of Congress

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail: it returns per-model {score, confidence, signals, raw_response}, uses a free default model, and requires a BYO API key for Anthropic calls with costs paid directly to Anthropic. This cost and return-shape disclosure goes 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 four compact sentences that front-load the core function and then add model selection, returns, and use cases. No filler or repetition of schema details.

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?

Although there is no output schema, the description fully specifies the return shape per model plus a combined view, covers cost/default behavior, and outlines representative use cases. This is sufficient for an agent to decide invocation and interpret results.

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

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

Schema coverage is 100% and the schema already provides per-parameter descriptions. The description adds default-model behavior (Workers AI Llama-3.3-70b is free), clarifies _apiKey is only needed for Anthropic, and explains the context parameter's disambiguation value.

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

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

The description uses a specific verb ('Probe') and resource ('one or more LLMs') and states the outcome (score visibility 0-100 per model), distinguishing it from general AI tools. It also lists concrete use cases that clarify its role in AI-marketing 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?

Clear use-case context is provided ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), indicating when this tool is appropriate. However, it does not explicitly exclude alternatives like scan_competitor_ai_presence, so it lacks contrast with 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses that the tool routes to 5,430 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is a fast single call. This adds substantial behavioral context beyond the structured hints.

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

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

The description is longer than typical but well-structured: it front-loads the most important guidance ('PREFER OVER WEB SEARCH'), gives examples, and then steps down to alternatives. While every sentence is informative, it could be trimmed slightly without losing meaning, so a 4 rather than 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?

For a broad, powerful tool with no output schema, the description is remarkably complete: it covers domains, usage cues, alternatives, behavior, citations, and even tier compatibility. It gives enough context for an agent to decide when to use this tool versus its siblings.

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 each parameter description is clear. The description does not add parameter-level semantics beyond what the schema already provides; it merely reinforces the natural-language nature of the question. Thus 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's purpose: it answers factual questions by routing to a large set of vetted data sources and returns cited answers. It differentiates itself from siblings by saying 'PREFER OVER WEB SEARCH' and 'START HERE', and specifically contrasts with ask_pipeworx_grounded and deep_research.

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

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

Provides explicit when-to-use guidance with trigger phrases ('what is', 'look up', 'find', etc.) and notes it should be used even when web search could answer. Explicitly names alternatives and when to step up: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions.

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

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

The annotations already declare read-only, idempotent, and non-destructive behavior. The description adds transparency about its experimental nature, noting that it may have routing improvements enabled live and that results are used for evaluation. It also clarifies that it's a full working router with no fallback. This context 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 efficient but includes specific details like the tool count and retirement date, which add color. Each sentence serves a purpose: defining the relationship to ask_pipeworx, providing current status, and giving usage guidance. It's slightly verbose but well-structured.

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

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

With no output schema, the description references the same response shape as ask_pipeworx, which is sufficient for a beta companion. It covers purpose, current state, usage, and behavior. It doesn't describe the return format in detail, but it's assumed known from ask_pipeworx, making it mostly complete.

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

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

Schema description coverage is 100%, with each parameter (including aliases) clearly documented. The description doesn't add parameter-specific semantics, but the schema fully handles this. Baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,430 tools and arguments. It distinguishes itself from the stable ask_pipeworx by its experimental routing improvements, explicitly naming the sibling and contrasting its current state. The specific verb is implicit in 'router'—it routes queries to tools, and the scope 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?

It explicitly says to use it 'exactly like ask_pipeworx when you want the newest routing,' which is a clear use case. It also mentions that results are compared against the stable router, implying a caution for stability. However, it doesn't explicitly say 'use ask_pipeworx for stable results,' leaving the exclusion to inference.

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

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

Discloses detailed behavioral traits beyond annotations: returns structured {answer, evidence, ...}, lists specific refusal reasons like 'not_in_source' and 'tool_error', explains that extraction uses 'ONLY what the tool result contains', and notes the extra LLM call cost. Annotations already declare readOnlyHint, so 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 dense but highly structured: starts with a one-line summary, then explains routing and extraction, gives the return format, refusal reasons, use cases, and performance tradeoff. Every sentence contributes value and the front-loading is effective for an agent scanning descriptions.

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 full burden of explaining return values and failure modes. It enumerates success fields and all refusal reasons, making the tool's behavioral contract fully transparent. Combined with explicit usage guidance, it is complete for an agent to invoke correctly.

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

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

Schema coverage is 100% and all six parameters are documented as aliases for 'question'. The description does not add parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies; the description's focus is on tool behavior, not parameter details.

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

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

The description clearly states the tool's function: 'Hallucination-resistant answer mode for high-stakes reads' and explicitly distinguishes it from sibling ask_pipeworx by noting 'same routing as ask_pipeworx' but with grounded extraction. The verb 'EXTRACTS' and resource (answer with evidence) is specific.

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

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

Provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on' and warns against inventing facts. It also gives a clear alternative: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost, covering when-not-to-use.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds substantial behavioral context: low-confidence matches short-circuit, closed markets return status, wide spreads carry tradeability warnings, cancellation-rule risk, news fallback flags, and suppressed analysis fields on low confidence. This goes far beyond the annotations and is crucial for safe invocation. No contradiction with annotations.

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

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

The description is long but tightly organized with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, RESOLUTION-RULE RISK). Every segment adds unique operational detail, and there is no fluff or repetition. The front-loaded purpose sentence and structured headers make it scannable despite its length.

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

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

With no output schema, the description carries the full burden for return-value semantics and does so thoroughly: it details the resolver contract, parent-event extractor, news fields, safety statuses, and cancellation-rule field. It also covers edge cases (429s, closed markets, wide spreads) and gives practical guidance (inspect match_confidence before trusting analysis).

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

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

The schema covers all three parameters (100% coverage), but the description adds meaningful context: market can be slug/URL/question text, depth maps quick vs thorough to evidence source counts, and include_raw explains size implications and when full payloads are needed. This enriches the schema without redundancy, though the schema already does 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 opens with a specific verb ('Research') and resource ('Polymarket bet') and explains the full workflow (resolve, classify, fan out, return evidence packet + comparison). It clearly distinguishes itself from sibling tools by focusing on Polymarket bets with a category-specific data fan-out pattern, and the classifiers and examples (crypto, Fed, sports) make the scope concrete.

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 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' which provides clear when-to-use guidance. It doesn't explicitly name alternative tools or exclusions, but the use-case phrases and the fan-out examples make the intended scope unambiguous, so it's a slight step below the highest tier.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), sorting by primary metric, and output format (paired data + 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 dense but every sentence earns its place. It starts with trigger phrases, then provides high-priority usage guidance, followed by data source details, sorting behavior, and output format. No redundancy; it is appropriately sized for a tool of this 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 lacking an output schema, the description clearly states what is returned (paired data + citation URIs), how results are ordered, what data sources are used, and edge-case handling (off-calendar fiscal years). It also constrains the input to 2-5 entities. This is comprehensive enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% with existing descriptions for type and values. The description adds deeper meaning by explaining how the 'type' parameter changes behavior (company vs drug data sources) and provides concrete examples for values (tickers/CIKs, drug names). This goes well beyond the schema's basic descriptions.

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

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

The description explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and lists numerous trigger phrases ('Compare X and Y', 'X vs Y', 'which is bigger', 'rank these companies'). This clearly distinguishes it from siblings like entity_profile which handles single entities. The verb 'compare' and resource scope 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: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also lists trigger phrases and notes it 'Replaces 8–15 sequential lookups,' implying the alternative of multiple single lookups. This meets the highest bar for usage guidance.

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

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

The description goes far beyond the readOnlyHint and idempotentHint annotations, disclosing account requirements, paid plan restrictions, latency expectations, decomposition and parallel routing behavior, explicit gaps promise, contradiction detection, semantic excerpting, and citation formats. It also clarifies that it returns gaps rather than inventing answers, which is critical behavioral context not present in annotations.

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

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

The description is long but well-structured and every sentence carries valuable operational detail. It is front-loaded with the critical account requirement. Minor redundancy exists with the schema's depth description, but the expansion provides deeper context. For the tool's complexity, the length is justified.

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

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

Given the absence of an output schema, the description thoroughly explains the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field). It covers prerequisites, performance expectations, edge-case behavior for news topics, and granular depth semantics, making it self-sufficient for an agent to invoke the tool correctly.

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

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

Although the schema already covers both parameters (question and depth) at 100%, the description significantly enriches their semantics. It explains that question is natural language and can be broad/multi-part, and details depth values (quick=3 facets, standard=5 with gap recovery and contradictions, thorough=8 with iterative hops and paid requirement) beyond the schema's concise enum 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 identifies the tool as 'Grounded multi-source research across Pipeworx's 1408 STRUCTURED data sources' in one call, explicitly contrasting it with open-web search. It differentiates from siblings by stating what it is NOT and when to prefer ask_pipeworx, making its purpose distinct and unambiguous.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and gives clear alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. This surpasses mere context by naming specific sibling tools and conditions.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it returns top-N tools with names, descriptions, and full input schemas (with curated examples), and that each result is ready to call directly without a second schema lookup. This explains what the agent gets back and the efficiency benefit.

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

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

The description is two sentences, front-loaded with the primary purpose, then usage scope, then return behavior. Every sentence serves a distinct function, and the long list of domains is a compact way to convey broad applicability without bloat.

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 discovery tool with no output schema, the description sufficiently explains what will be returned (names, descriptions, full schemas, examples) and how to use it. The sibling tools are numerous, but the 'call first' guidance and domain list give the agent enough context to decide when this tool is appropriate. No missing critical information.

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 all 6 parameters, so the schema already provides full semantic details. The description reinforces that query is a natural language description but adds little beyond that. Parameters like limit are already documented in the schema, so this dimension is adequately covered but not enhanced.

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

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

The description opens with 'Find tools by describing the data or task,' which clearly identifies the verb (find) and resource (tools). It immediately distinguishes this discovery tool from the many specific data tools in the sibling list by framing it as the meta-tool for locating other tools.

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

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

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' This gives clear context and an explicit directive, though it doesn't name alternatives it's the natural 'start here' 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 and idempotentHint=true, but the description adds substantial behavioral detail: it fans out across five sources, soft-fails on the sunsetting USPTO API, uses a GDELT→GNews fallback, and returns a specific list of fields. This goes well beyond the basic safety profile.

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 efficient: it packs examples, usage priority, data sources, return fields, and a limitation into a few sentences. No filler; every clause serves a 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?

Given there is no output schema, the description enumerates the returned fields (cik, company_name, recent_filings URIs, fundamentals, patents, news, LEI) and documents known limitations (patent sunset, unsupported names). It also provides fallback behavior, making it a thorough description for a complex tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the ticker/CIK instructions and adds the note about names not being supported, but does not add syntax or format details beyond what the schema already provides. It does reinforce the resolve_entity alternative.

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 concrete query examples ('Tell me about X', 'research Acme') and then states it produces a 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from chained single-pack lookups by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.'

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

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

Explicitly says to use this tool when the user asks for a holistic view ('ALWAYS PREFER ... when the user asks for a holistic view'). It also notes that names are not supported and directs the agent to 'use resolve_entity first if you only have a name', which is a clear alternative.

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

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

Annotations already convey destructiveness and idempotency. The description adds behavioral context: that it targets previously stored memories, implies irreversibility by saying 'Delete,' and explains the 'clear sensitive data' use case. This goes beyond the structured 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?

Two concise sentences: the first states the action, the second provides usage guidance and sibling pairings. No filler or redundancy; every sentence earns its place.

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

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

For a simple one-parameter tool with annotations covering destructive/idempotent behavior and no output schema, the description fully covers purpose, when to use, and related tools. Nothing essential is missing.

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

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

The input schema fully describes the 'key' parameter with a clear description and an example, and schema coverage is 100%. The description adds no new parameter-specific meaning beyond restating 'by key.' Baseline 3 is appropriate when 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 the action: 'Delete a previously stored memory by key,' specifying the verb (delete), resource (memory), and method (by key). It distinguishes itself from siblings like remember and recall by framing deletion against storage and retrieval.

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

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

The description gives explicit usage scenarios ('when context is stale, the task is done, or you want to clear sensitive data') and directs pairing with 'remember and recall,' effectively indicating when to use this tool versus its complementary siblings.

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

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

The description adds process details beyond annotations: it fetches the page, extracts title/description/key links, and emits a text blob. This supplements the readOnlyHint and openWorldHint annotations with concrete behavior. It doesn't disclose rate limits or auth, but for a read-only tool with these annotations, it's sufficient.

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

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

The description is four sentences with no wasted words. It front-loads the core purpose, explains the mechanism, describes the output format, and lists use cases. Every sentence contributes meaning.

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

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

The tool is simple (2 params, 1 required), annotated as read-only and idempotent, and the description explains the output is a single text blob. It doesn't cover error handling or edge cases, but for this complexity level, the description is sufficiently complete.

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

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

The input schema covers 100% of parameters with descriptions (url, max_links). The description does not add parameter-specific details beyond the schema, but the baseline is 3 because schema coverage is high. No extra semantic information is provided about 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 uses a specific verb ('Generate') and resource ('production-ready llms.txt file for any URL'), then details the process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This clearly distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on visibility auditing rather than generating llms.txt content.

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

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

The description provides clear use cases ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') but does not explicitly contrast with sibling tools or state when not to use it. Thus it has clear context but no exclusions.

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

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

Annotations already declare read-only/idempotent/non-destructive behavior, so the description adds value by specifying the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying the scope ('caller's'). This is useful 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 two sentences, front-loaded with the primary action, and every clause earns its place. It efficiently combines the action, return fields, and usage guidance without redundancy.

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

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

For a simple read-only list tool with no output schema, the description covers the key aspects: scope, return fields, and when to use. The only minor gap is explicitly explaining include_inactive behavior, but the schema covers that, so the description is reasonably complete.

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

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

Schema coverage is 100% for the only parameter (include_inactive), and its description in the schema is sufficient. The tool description adds no additional semantic detail beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('List') and resource ('the caller's active subscriptions'), and clearly distinguishes from sibling tools like subscribe/unsubscribe by framing this as the review-before-adding or find-id-to-cancel step. The scope is unambiguous.

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

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

It gives explicit use cases: 'review what you're monitoring before adding more' and 'to find an id to cancel.' These imply the alternatives (subscribe and unsubscribe) without naming them, and it doesn't explicitly state when not to use, but the guidance is sufficiently clear for the intended 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 are all false, providing minimal behavioral signal. The description compensates by disclosing rate limits ('Rate-limited to 5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), and processing cadence ('The team reads digests daily'). It also clarifies that reporting non-Pipeworx tools will delay resolution. This adds meaningful context beyond the annotations, though it could have explicitly stated expected response 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 front-loads the core purpose in the first sentence, making the tool's intent immediately clear. Subsequent sentences earn their place by covering usage boundaries, content guidance, and operational details. Though it is a bit verbose with multiple clauses, no sentence is wasted and the structure flows logically from action to when-to-use to exclusions to instructions.

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 feedback submission tool with no output schema, the description covers all needed context: what to report, when to use it, what not to report, rate limiting, quota impact, and how feedback is processed. The nested 'context' object is fully documented in the schema, and the description's additional guidance on mentioning Pipeworx tools makes the tool's usage complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by instructing on message content: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This goes beyond the schema's 'plain text' description and helps the agent craft effective feedback. The enum values for type are fully explained in the schema, and the description reinforces the meaning of feature vs. data_gap.

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 command: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly identifies the tool's action (sending feedback) and resource (Pipeworx team), and distinguishes it from sibling research, subscription, and memory tools. The title 'Send Pipeworx Feedback' aligns with the description, leaving no ambiguity.

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is exemplary for guiding an agent's tool selection.

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

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

Beyond the read-only and idempotent annotations, the description reveals caching (5min-1h), data provenance (CF analytics-engine), and privacy (no PII). This gives agents important context about data freshness and trustworthiness.

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 but front-loaded with the main purpose. Each sentence adds value: the use-case bullet points and the data provenance note are useful, though slightly longer than minimal.

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

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

The description covers the return output (top tools, top packs, call volume), window options, use cases, data source, privacy, and caching. Since no output schema exists, this adequately explains what to expect from the call.

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

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

The only parameter `window` is fully described in the schema with enum values and semantics. The description mentions the window options but adds no information beyond the schema's coverage, 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 states the tool returns trending usage data: top tools, top packs, and total call volume over a recent window. This distinguishes it from siblings like discover_tools by focusing on aggregated multi-agent call activity rather than static discovery.

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

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

The 'Useful for' list provides three concrete use cases: finding hot data sources for current events, confirming canonical choices, and aligning use cases with agent demand. It does not explicitly name alternatives or exclusions, but the context is clear.

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

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

Even though annotations already declare readOnlyHint and idempotentHint, the description adds substantial behavioral context: the Jaccard similarity semantic anchor, the partition filter dropping placeholder slugs, the >20% placeholder threshold returning null, and the fill check explaining that realizable_edge_pp ≤ 0 means the overround is not in the book. This goes far beyond the annotations and tells the agent exactly what outputs to expect and what not to trade.

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: main purpose, mode explanations, semantic anchor, partition filter, response outline, and fill check caveat. All sentences contribute useful information, and the most important action ('Call with NO args...') is front-loaded. Slightly verbose, but every added detail serves a practical purpose; could be tightened without harming 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?

For a complex tool with two modes, optional parameters, and no output schema, the description is remarkably complete. It describes the response structure (opportunities[], partition_check{...}), the fill check behavior, edge cases (placeholder slugs, low similarity), and when not to trade. The annotations provide safety guarantees, and the description fills in all operational details needed to use the tool correctly.

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

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

The schema already covers both parameters with descriptions, giving baseline 3. The description significantly enriches this: it provides concrete examples of event slugs ('fed-decision-may-2026'), topic seeds ('Strait of Hormuz traffic returns to normal'), and details on the output behavior for each mode (e.g., partition_check fields, skipped_low_similarity). This far exceeds the 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 opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk by its unique detection methodology. The two modes (event, topic) are also explicitly described, making the tool's purpose unambiguous.

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

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

The description gives explicit mode-selection guidance: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', and 'topic for a themed cross-event scan.' It also explains when cross-event mode is advantageous and directs users to polymarket_fill_risk for custom sizing. However, it does not explicitly compare against sibling tools like polymarket_edges or polymarket_edge_tracker, so it falls slightly short of full alternative differentiation.

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, but the description adds substantial behavioral detail: 1-hour KV caching keyed on knobs, the 24h-move warning, the exclusion of Fed bets from ranking with rationale, the 'rare-by-design' nature of concentrated longshots with relaxed gates, and the diagnostics funnel so callers see why segments are empty. These go beyond the annotations without contradiction.

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

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

The description is very long and dense, including highly specific details like per-sport alpha values (tennis 1.02, soccer 1.10, MMA 1.15) and model family formulas that go beyond what an agent needs to invoke the tool. It is well-structured with capitalized section headers and the core purpose is front-loaded, but it is not appropriately sized for quick consumption.

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 must fully explain the return structure, which it does thoroughly: top-level fields (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and the meaning of gates and filters. It also covers caching, edge calculations, and the rationale for excluding Fed bets, making it highly complete for a complex tool.

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

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

Schema description coverage is 100%, and each parameter already has a detailed description (defaults, units, examples). The tool description adds minimal extra semantic value, mostly referencing knobs like min_liquidity and max_spread_pp and explaining the special case of min_partition_leg_kelly for partition arbitrage. Since the schema fully documents the parameters, a 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 opening sentence explicitly states the verb ('Scan'), resource ('top Polymarket markets'), and outcome ('return opportunities where Pipeworx data disagrees with market price'), giving a precise purpose. It clearly distinguishes this from sibling tools like polymarket_arbitrage by focusing on Pipeworx data disagreement and framing it as 'what should I bet on today'.

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

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

The description provides clear context for when to use this tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains the three response segments and the tradeable-edge knobs, giving practical usage guidance. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, but the description adds deep behavioral context: snapshot gaps due to cache-miss, 60-day TTL limits, signed edge values (negative = SELL YES), decay computed on absolute value, and the response structure's meaning (lifespan_days as a 'competition clock'). This goes far 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?

Though long, the description is dense and every sentence earns its place. It is front-loaded with the core purpose, then logically organized into Args, RESPONSE, and LIMITS sections. The structured labels make it scannable despite the detail necessary for a tool without an output schema.

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

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

For a tool with no output schema and two parameters, the description fully covers the response format (tracked, expired, snapshot_dates), edge cases (gaps, TTL, close vs. intraday), and why the data behaves that way. It leaves no significant ambiguity for an agent deciding whether to call it or interpreting results.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the defaults ('days default 14, max 30', 'window default 1wk') without adding significant new meaning beyond labeling window as a 'snapshot family.' It does not conflict with the schema but also doesn't elevate it.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly states the tool's function (tracking edge longevity and decay) and distinguishes it from sibling tools like polymarket_edges by focusing on historical persistence rather than current edge calculation.

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

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

The description provides clear use context ('Answers how long has this edge existed and is it shrinking?') and even gives a concrete trading scenario (fresh vs. 3-week-old edge). However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of full 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?

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, the description adds rich behavioral context: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), highlights forced directional risk, and explains that partial basket fills convert an arb into an unhedged directional position. This goes far 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 dense and structured with mode-specific breakdowns, but it is a long single paragraph. It is front-loaded with the core purpose and every sentence adds value, but it could benefit from formatting (e.g., bullet points or section labels) to improve scannability. Slightly wordy but warranted 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?

This is a complex tool with two modes, no output schema, and no enumerated parameters. The description fully compensates by enumerating the return fields for both single-market and basket modes, explaining the verdict system, thin_legs, forced_directional_risk, and the profit/capture calculations. It also addresses edge cases like default behavior and interpretation of size_usd, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, giving a baseline of 3, but the description significantly extends parameter meaning: it clarifies that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode, details the default side behavior in basket mode (auto from partition sum), and notes the clamp range (10–1,000,000) not present in the schema.

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

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

The description opens with a specific verb+resource+scope: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and differentiates from sibling tools by stating this is a pre-trade risk check for polymarket_arbitrage and polymarket_edges signals.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable) and warns about the danger of partial fills, giving clear when-to-use and why-not-to-skip 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?

The description extensively discloses behavioral traits beyond annotations, including compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs 0), temporal_alignment significance, and skipped_cross_type/subtype counters. It explains that mismatched bet shapes mean 'no arb exists' and that aligned:false makes spreads 'mathematically meaningless,' providing critical decision-making context. The read-only and non-destructive nature is implied throughout, consistent with annotations.

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

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

The description is long but well-organized with clear sections (modes, response, safety fields, warnings) and is front-loaded with the core purpose. Every sentence adds value, including the final caveat about pre-mapped topics. It is appropriately sized for the tool's complexity, though slightly dense, so not a perfect 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?

No output schema exists, so the description must explain return values, and it does thoroughly: 'each venue's leg-by-leg prices (raw probability 0-1) plus matched spread[].top_spreads_pp (Kalshi − Polymarket).' It also covers edge cases like non-equivalent bet shapes, unrelated events, and temporal misalignment, making the tool usable without additional 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%, so baseline is 3. The description adds meaningful semantics by explaining that 'topic' auto-fetches the matching event on each venue and that explicit tickers 'Override the topic-mapped' side. This enriches the parameter meaning beyond the schema's simple field descriptions, earning 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?

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which is a specific verb+resource+scope statement. It clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and explicitly naming the two venues.

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 defines two modes ('topic' shortcuts and explicit tickers) and provides clear context on when each is appropriate. It also warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' giving concrete usage guidance. However, it does not explicitly mention alternative tools for single-venue arbitrage or general comparison, so exclusions are not spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds useful behavioral details: scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the omit-key behavior for listing. 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 three sentences, front-loaded with the core action, and every sentence contributes—purpose, usage context, and scoping. No filler or redundancy.

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

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

Given the simple optional-parameter schema, full annotations, and no output schema, the description covers all necessary aspects: what it does, when to use it, how it relates to sibling tools, and scoping. It implicitly explains the return value (saved values or list of keys).

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

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

The schema already covers the single parameter (key) with a clear description. The tool description adds meaning by giving concrete examples of keys (user's target ticker, an address, prior research notes), helping the agent understand what kind of data to expect.

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 specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It differentiates from sibling tools by explicitly pairing with 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?

It gives explicit usage context: 'Use to look up context the agent stored earlier… without re-deriving it from scratch.' It also names alternatives: 'Pair with remember to save, forget to delete.'

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

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

The description states that setting mark_read:true 'flag[s] returned events read,' which mutates the feed's read state. This directly contradicts the annotation readOnlyHint=true, as the tool is not strictly read-only. The contradiction is significant enough to warrant a score of 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 four sentences long, front-loaded with the core purpose, and every sentence adds meaningful information. It avoids fluff and presents details in a logical order (purpose, return fields, filters, side effects, alternative access).

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

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

The description covers the main functionality, return fields, filtering options, read-flag behavior, and even provides an alternate HTTP endpoint for scripts/dashboards. It lacks explicit ordering details or edge-case behavior, but overall it is reasonably complete for a 5-parameter tool with no 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%, so the baseline is 3. The description adds value by giving examples ('sec_8k'), explaining mark_read behavior in detail, and clarifying the ISO timestamp format for 'since'. It does not elaborate on limit/unread_only, but the schema already covers those adequately.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), and distinguishes it from siblings like list_subscriptions and recent_changes by focusing on subscription feed alerts. The return characteristics (source, citation_uri, raw payload) further clarify its function.

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

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

The description provides useful context: 'Polls work fine' and points to an HTTP endpoint for scripts/dashboards, suggesting this tool is suited for agent-driven polling. It does not explicitly name alternative tools or state when not to use, but the guidance is clear enough for typical usage.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses important behaviors: fan-out to SEC EDGAR/GDELT/USPTO, rate-limit fallback logic, the PatentsView API sunset and soft-fail behavior, and the citation URI output. This materially enhances the agent's understanding of side effects and reliability without contradicting annotations.

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

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

The description is long but information-dense, with no filler. It front-loads the primary purpose and user triggers, then packs fallback logic, parameter semantics, and output shape into a compact flow. The density is justified by the tool's complexity, though it could be slightly tightened (e.g., splitting output format into a separate line).

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

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

Without an output schema, the description fully covers return values ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also covers edge cases (PatentsView sunset), fallback routing, and the entity_profile alternative, making it complete for an agent to decide and invoke correctly.

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

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

Although schema coverage is 100%, the description adds critical semantic detail: `since` formats ('ISO date ("2026-04-01") or relative ("7d", "30d", "3m", "1y")'), the meaning of `value` (ticker or zero-padded CIK), and the recommended default ('Use "30d" or "1m"'). This goes beyond the schema's terse descriptions.

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

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

The description opens with exact user intents ('What's new with X' / 'latest on Y') and states a specific verb+resource: 'change feed for a company in the last N days/weeks/months.' It explicitly distinguishes from sibling tool entity_profile ('Use entity_profile instead when you want the static profile'), making the boundary 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 concrete when-to-use triggers ('what happened to Z this week / month / quarter'), explains the single-call fan-out pattern, and explicitly names the alternative entity_profile for static profiles. It also notes the fallback behavior (GDELT→GNews, PatentsView soft-fail), giving the agent clear decision 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 cover idempotence and non-destructiveness; the description adds meaningful behavioral context beyond that: key-value pairs are scoped by identifier, and retention differs for authenticated vs anonymous sessions. This enriches the agent's understanding of side effects and persistence.

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

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

Three sentences, front-loaded with the core action, followed by usage triggers, storage details, and companion tools. Every sentence earns its place; no redundancy or filler.

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

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

For a simple 2-parameter tool with no output schema, the description covers all essential aspects: purpose, when to use, storage behavior, retention policy, and related tools. Nothing important is missing.

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

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

Schema covers both parameters with examples (100% coverage), so baseline is 3. The description adds value by framing the parameters as a key-value pair and giving real-world key examples (resolved ticker, target address), which helps the agent form correct mental models of key/value usage.

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 ('Save data the agent will need to reuse later') and clearly defines the tool's function. It differentiates from siblings by explicitly mentioning recall and forget as companion tools, making the scope unambiguous.

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

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

Provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference') and states that it prevents redundant lookups. Also names companion tools (recall, forget) for related actions, effectively steering the agent.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable behavioral context: it cascades through several lookup endpoints, auto-disambiguates company inputs, and returns specific citation URIs. It goes beyond the annotations without contradicting them, but it stops short of covering potential edge cases or failure modes.

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

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

The description is dense but well-organized. It front-loads with example user queries to quickly communicate intent, then breaks down supported types and return details. Every sentence adds value, and the structure uses clear labels ('SUPPORTED TYPES', 'company', 'drug') to keep the length manageable.

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

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

Despite the lack of an output schema, the description fully explains what is returned for each entity type (ticker, CIK, company_name, citation URI; RxCUI, ingredient, brand, citation URI). It also covers input formats, internal behavior, and the tool's role relative to other tools. This 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%, but the description adds significant meaning beyond the schema. It explains the 'type' enum values and what each returns, and gives concrete examples for 'value' (AAPL, CIK, 'ozempic', 'metformin'). It also clarifies that company input can be a ticker, CIK, or name with auto-disambiguation, which is not fully captured 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 states a specific action: resolve user-spoken names to canonical/official identifiers. It provides concrete example queries ('What's the ticker for…'), names the resource types (company, drug), and explicitly distinguishes itself from other tools by noting that 'other tools require as input' and recommending 'Use FIRST whenever you have a name but need an ID.'

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: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups and cascades through multiple endpoints. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5 for explicit when/when-not/alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds meaningful behavioral details beyond the annotations: it discloses that the tool internally probes with ai_visibility_check, ranks results by score, and returns specific fields (score, confidence, signal density). This is more transparent than a simple 'list' tool, though it doesn't discuss rate limits or failure modes.

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

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

The description is two sentences plus a quote and an output note. It is front-loaded with the core verb and resource, includes a concrete use case, and specifies return fields. Every sentence earns its place with no redundancy.

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

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

The tool has 4 parameters and no output schema, but the description explains the return format ('ranked list with score, confidence, signal density per entity') and the mechanism (probes with ai_visibility_check). It misses mention of the models/_apiKey parameters, but these are fully covered by the schema, so completeness is strong but not perfect.

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

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

Schema description coverage is 100%, with all four parameters documented. The description adds only marginal semantic value by referring to 'your brand + N competitors', which aligns with the already detailed entities parameter. Since the schema carries the load, a baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly differentiates from the sibling ai_visibility_check by explicitly mentioning it as the underlying probe and focusing on multi-entity comparison. The use case quote further clarifies the purpose.

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

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

The description states when to use it: 'Useful for competitive AI-marketing audits' and provides an explicit example question. It implies that for single-entity checks you'd use ai_visibility_check instead, though it doesn't name alternative tools explicitly. This is clear context with an implicit exclusion.

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, and idempotentHint. The description adds significant behavioral context: composite fan-out, partial failure degradation, and the 5-30s latency for bundlephobia's first measurement, plus the sources_failed field. 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?

Though long, the description is densely packed and well-structured: purpose, usage guidance, output contract, and failure behavior. It front-loads the main verb and uses dashes to organize subsidiary details without redundancy.

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

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

With no output schema, the description enumerates the full return shape: summary block fields, per-advisory detail, links, alternative versions, and the sources_failed error reporting. It also specifies ecosystem scope. This is complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, with both 'package' and 'version' clearly documented (including scoped packages and default-to-latest behavior). The description itself doesn't add parameter-specific details beyond that, so baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call' and clearly states it fans out across deps.dev and bundlephobia. This distinguishes it from sibling tools like scan_competitor_ai_presence.

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 when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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, the description discloses technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and the 200K char cap with truncation flag. It also mentions return elements (offsets, scores) and the ability to verify verbatim quotes—all 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 well-structured and efficient: a one-line purpose, followed by usage context, then technical details. Every sentence earns its place, with no filler or redundancy.

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

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

Despite having no output schema, the description explains what the agent can expect (top-N passages with character offsets and similarity scores) and covers input constraints (200K cap, truncation). Combined with rich annotations and full schema coverage, it is complete for this 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% (baseline 3), and the description adds valuable context: text is described as 'fetched record' with concrete examples, query gets usage examples, and limit is implied by top-N. While not critical, these examples help an agent craft correct parameter values.

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

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

The description clearly states a specific verb and resource: semantic search inside a fetched record. It gives concrete examples (SEC 10-K, article) and distinguishes itself from siblings like ask_pipeworx by focusing on searching within a user-supplied text.

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 when to use the tool ('Use when the record is too big to cram into the prompt') and names the complementary tool ask_pipeworx_grounded, explaining how they work together. This provides clear context and differentiation from alternatives.

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

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

The description goes far beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false). It discloses that subscriptions persist and require authentication, returns a subscription id, always-on feed behavior, and specific side effects like email/SMS delivery with a 10/day cap and phone verification. The webhook details are in the schema, but the description itself is rich in behavioral context.

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

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

The description is lengthy but well-structured: purpose, requirements, supported types, delivery channels. Every clause adds useful detail. The main issue is the 'Supported types' enumeration lists only three of five types, which is not strictly accurate and adds a little confusion, though it doesn't waste words. Overall it is appropriately concise for the tool's complexity.

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

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

Given the tool's complexity (multiple subscription types, delivery options, auth requirement) and lack of an output schema, the description covers most essentials: return value, auth prerequisite, feed behavior, and delivery limits. The notable gap is the partial list of supported types, which could mislead an agent into thinking only three types exist. The schema fills this gap, so the collective picture is strong, but the description alone is not fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by providing concrete examples for three of five types (e.g., reinterpretation of 'items:["5.02"]' as an officer change, Polymarket topic 'fed', FRED series_id 'UNRATE') and explaining delivery channel constraints (SMS cap, phone verification). However, it omits two supported types (patent_grant, clinical_trial) from its 'Supported types' list, creating a minor incompleteness that is partially offset by the schema.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream,' which is a specific verb+resource pair that clearly distinguishes this tool from sibling tools like 'list_subscriptions' or 'recent_alerts.' It also clarifies return value and lists concrete supported types with examples, leaving no ambiguity about the tool's function.

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

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

The description provides strong usage context: it is for proactive monitoring, requires a Pipeworx OAuth account (excluding anonymous and BYO users), and explains delivery channels (feed always on, optional email/SMS with constraints). It does not explicitly say 'use instead of X' or 'when not to use,' but the proactive-monitoring framing and complementary mention of recent_alerts guide appropriate usage.

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

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

The description goes beyond the read-only/idempotent annotations by explaining the return payload: category-bucketed example questions with exact tool and argument shapes, sourced from the live catalog. It also clarifies the effect of omitting vs passing the topic parameter. No contradictions with annotations.

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

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

The description is verbose but purposeful, opening with a list of user intents that clarify the tool's scope. It could be slightly shorter, but each section (purpose, return value, usage, when to use) is clearly delineated and 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?

With no output schema, the description adequately explains the return format and content. It also covers the tool's role as an onboarding aid and how it connects to meta-tools, providing a complete picture for a low-complexity tool with one optional parameter.

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

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

The input schema already provides full coverage of the `topic` parameter, including the list of valid values and the meaning of omission. The description only adds a few examples ('finance', 'pharma', 'betting') and rephrases the same behavior, adding minimal value beyond the schema.

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

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

The description clearly identifies the tool as the onboarding entry point for an agent, specifically returning category-bucketed example questions. It distinguishes itself by focusing on 'what can I ask' and references meta-tools, making it distinct from sibling tools like discover_tools.

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

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

The description gives explicit guidance on when to use this tool ('Use this FIRST when you do not yet know what Pipeworx can do for you') and explains the parameter behavior (omit for full spread, pass topic to focus). However, it does not provide explicit alternatives or exclusions, such as pointing to discover_tools for general tool discovery.

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 meaningfully extends beyond annotations by explaining that the row is deactivated rather than deleted, preserving event history. It also discloses the ownership enforcement, which is a behavioral trait not captured in the annotations. This aligns with the idempotent and non-destructive hints.

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

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

The description is two sentences, front-loaded with the main action, and no wasted words. It efficiently conveys purpose, constraints, and aftermath.

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 and no output schema, the description is complete. It explains the cancellation action, ownership rule, and the deactivation mechanism, referencing recent_alerts for related context. No critical information appears missing.

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

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

The schema already provides 100% coverage for the single parameter (id) with a clear description ('Subscription id (uuid) returned by subscribe'). The tool description does not add additional semantic context beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscription). It differentiates from siblings like subscribe and list_subscriptions by focusing on cancellation and adding ownership constraints. The behavior is specific and unambiguous.

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

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

Provides clear context for when to use: cancelling a subscription, with the constraint that only own subscriptions can be cancelled. It also explains the effect (deactivation vs deletion) and points to recent_alerts for historical data. However, it does not explicitly mention alternatives or exclusions beyond ownership.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds rich behavioral detail: the two-path routing (SEC EDGAR/XBRL vs grounded pipeline), the exact percent-delta math, the verdict categories, and the inclusion of citations and reasoning. This goes well beyond the structured annotations and gives the agent a precise mental model of what happens when the tool is invoked.

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

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

The description is well-structured and front-loaded with the tool's purpose, but it is somewhat verbose with a long list of synonymous phrasings ('Is it true that…', 'fact check', etc.) and a value statement about replacing sequential calls. These are useful but could be condensed without losing meaning. It remains a single coherent paragraph with high information 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?

Given no output schema, the description fully covers the return value (verdict types, actual value, citation, reasoning). It also explains the routing logic, the scope of supported claims, and the tolerance behavior. The tool is complex, and the description leaves no critical gaps for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself does not add significant parameter-level detail beyond what the schema provides; it mentions 'exact percent-delta math' but the schema already explains tolerance_pct and claim examples. The schema carries the burden, and the description's value lies elsewhere.

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

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

The description clearly states a specific verb ('verify', 'fact check') and resource ('natural-language claim') and differentiates from siblings by focusing on returning a verdict against authoritative sources. It lists common phrasings, making the intent unmistakable. It also distinguishes itself from other research tools by emphasizing claim verification with structured and grounded pipelines.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides internal routing guidance (financial vs. other claims) but does not mention alternative tools or when not to use this tool. This is clear context without exclusions, matching the '4' level.

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