Seo Keywords

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses important behavioral details: default model, cost implications of using a BYO API key, and the exact return shape (per-model score/confidence/signals/raw_response plus combined view). This goes well beyond what annotations provide, offering practical guidance for invocation.

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 well-structured sentences deliver all essential information: what it does, default behavior, cost consideration, return format, and common use cases. No wasted words; the description is front-loaded with the core purpose and immediately usable 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?

Given no output schema, the description appropriately explains the return structure and the main behavior. It covers global defaults and cost, but could briefly clarify 'signals' or 'combined view' for full completeness. However, these are minor gaps and the overall description is adequate for a moderately complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the default model when 'models' is omitted and clarifying that passing '_apiKey' incurs direct Anthropic charges, which is not fully captured in the schema. It reinforces parameter relationships and defaults without being redundant.

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

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

The description clearly states the tool's function: probing LLMs for knowledge about an entity and scoring visibility on a 0-100 scale. It specifies the resource (business/brand/product/topic) and distinguishes itself from siblings by emphasizing multi-model probing and a quantitative score. The verb 'Probe' is specific and the outcome is well-defined.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that help an agent decide when to employ it. It does not explicitly name alternatives or exclusion criteria, but the context is sufficient for appropriate selection among the listed siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context by explaining routing to thousands of sources, auto-filling arguments, returning stable pipeworx:// citation URIs, and working on every tier with one fast call. 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 long (~150 words) but well-structured: opening command, domain list, examples, and escalation path to alternatives. It is front-loaded with the most critical usage guidance, though a few phrases could be tightened.

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 (routing to thousands of sources) and absence of an output schema, the description provides sufficient context: it explains output format (structured answer with citation URIs), mentions one-fast-call performance, and covers both general and edge-case usage (news, breaking news). It is complete enough for an agent to select and invoke the tool.

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

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

The input schema already has 100% coverage with a clear description for 'question' and all aliases. The description adds value with concrete example queries ('current US unemployment rate', 'Apple's latest 10-K') that illustrate the expected natural language input, but does not substantially extend schema semantics beyond those examples.

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 routes factual questions to 5,417 tools across 1,405 verified sources and returns structured answers with citation URIs. It distinguishes from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different needs.

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 opens with 'PREFER OVER WEB SEARCH' and provides explicit guidance: 'START HERE for most questions' and 'Step up only when needed', naming ask_pipeworx_grounded and deep_research for specific scenarios. It also lists trigger phrases like 'what is', 'look up', 'find', making when-to-use very 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds critical behavioral context: it is a beta with candidate routing improvements enabled live, the current state (no candidate active, retired on 2026-07-26), and that results are compared against the stable router. This fully discloses the experimental edge 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 about 4 sentences, each carrying useful information: beta purpose, current state, usage guidance, and reassurance of full functionality. It is front-loaded with the core identity and remains appropriately dense without becoming bloated.

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 a beta variant of a known router; the description covers its purpose, current parity with stable, usage direction, and that the response shape matches ask_pipeworx. With no output schema, the description does not detail return values, but the reference to identical response shape provides enough context for an agent familiar with ask_pipeworx.

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

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

The input schema already provides 100% coverage with clear descriptions for the single required 'question' parameter and its aliases. The description adds no extra parameter semantics beyond saying 'same arguments' as ask_pipeworx, so it does not enhance what the schema already offers. Baseline 3 is appropriate.

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

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

The description clearly states this is the beta version of ask_pipeworx with an identical universal router (5,417 tools, same arguments, same response shape) and experimental routing improvements. It differentiates from siblings by specifying the beta nature and live candidate testing mechanism, making it distinct from the stable ask_pipeworx.

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

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

The description explicitly tells when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names the stable router as the alternative ('results are compared against the stable router') and reassures functionality with 'Falls back to nothing — this IS a full working router.'

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 openWorldHint=true, but the description adds substantial behavioral detail: the exact success response shape ({answer, evidence, confidence, source, fetched_at}), explicit refusal reasons (not_in_source, no_tool_match, etc.), and the guarantee that answers are drawn only from tool results. It also discloses the extra LLM call cost. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then flows logically: mechanism, output contract, usage guidance, and tradeoff. Every sentence adds necessary context (routing, extraction, refusal modes, cost) without redundancy or filler. For a tool with this behavioral 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?

No output schema exists, so the description fully specifies the return object and the refusal object with all possible refusal_reason values. It also covers when to use, cost tradeoff, and alternatives, making the description sufficient for safe invocation even in high-stakes scenarios.

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%; all six parameters are aliases for 'question' and are described in the schema itself. The description does not add parameter-level insight beyond saying the tool 'fills arguments' during routing, which is generic. Baseline 3 applies since the schema carries the weight.

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 purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly differentiates from the sibling ask_pipeworx by emphasizing extraction using ONLY tool result content and returning evidence. The verb 'extracts' plus the resource scope (tool results) makes the function unmistakable.

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

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

Provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' It also names the alternative (ask_pipeworx) and gives a cost-based heuristic, which is actionable and distinguishes when to use this tool vs the sibling.

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

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

Extensive behavioral disclosure beyond annotations: parallel fan-out mechanics, resolver contract with confidence levels, status names ('low_confidence_match', 'market_closed_or_inactive'), news fallback fields, wide-spread tradeability warnings, and cancellation-rule risk. This adds significant context while remaining consistent with the readOnly/openWorld/idempotent annotations.

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

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

The description is long but structured into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), making it navigable. Every sentence adds operational value; there is no redundancy. However, the length is substantial, so it loses one point for not being more compact, though it remains well-organized.

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

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

Given no output schema, the description thoroughly covers response structures (market/analysis/evidence), resolver match confidence, parent-event extraction, news fallback behavior, safety statuses, and cancellation rules. It anticipates edge cases (e.g., closed markets, wide spreads) and provides procedural guidance, making it 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?

Although schema coverage is 100%, the description deepens meaning: it explains the market parameter accepts slug/URL/question, clarifies depth defaults and trade-offs ('quick = 2-3 sources, thorough = full fan-out'), and details include_raw's impact on response size and use cases. This goes well beyond schema descriptions.

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

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

The opening sentence states a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further distinguishes itself by listing classifiers, fan-out examples, and explicit use cases ('should I bet on X'). This clearly separates it from sibling Polymarket tools like arbitrage or edge tracking.

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

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

The description provides explicit use cases ('Use for ...') and explains input formats (slug, URL, question). It also covers blocking statuses and when to inspect resolver fields. However, it does not name alternative tools for when not to use this one, falling just short of the highest bar for explicit exclusions/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 adds substantial behavioral context beyond annotations: it discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), fiscal year handling (AAPL Sep, NVDA Jan), sorting by primary metric, and citation URI return format. Annotations already declare read-only, so the description enriches rather than contradicts.

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 all sentences add value: trigger phrases, definition, usage preference, type-specific data sources, sorting behavior, and output format. It could be slightly tighter by eliminating redundant trigger examples, but earns a 4 due to 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 adequately covers inputs, behavior, outputs, and performance benefits. It explains what data is pulled per type, how results are sorted, and what is returned (paired data + URIs), making the tool fully comprehensible for an agent.

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

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

Though schema has 100% parameter descriptions, the description deepens meaning: type='company' pulls 10-K revenue/net income/cash/long-term debt, type='drug' pulls FAERS and FDA counts, and values examples clarify expected formats (tickers/CIKs vs. drug names). This goes well beyond the schema's enum and array notes.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs, with explicit trigger phrases and a resource scope. It distinguishes from sibling tools like entity_profile or resolve_entity by focusing on comparison rather than single-entity lookup.

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 guidance with 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and reinforces the benefit with 'Replaces 8–15 sequential lookups.' This makes the intended use case unmistakable and directly contrasts with an alternative approach.

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

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

The description adds substantial behavioral context beyond annotations: account requirements, paid depth tier, execution time (15-60s), return of gaps[] when data is absent, never inventing answers, second-hop behavior per depth, contradictions[], and semantic excerpting. This is rich, non-redundant disclosure.

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

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

The description is long but every sentence earns its place, covering critical account, usage, and behavioral details. It is front-loaded with the account requirement and alternatives, though a touch more paragraph separation would improve scanability.

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

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

With no output schema, the description thoroughly explains the return structure (findings packet, gaps[], contradictions[], hop, citation_uri) and covers timing, account constraints, and exclusions. For a complex multi-tool research orchestrator, this is complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds valuable parameter context, such as depth:'thorough' requiring a paid plan, and depth-specific behavior like gap recovery and contradiction scanning. This goes beyond the schema's prose.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1405 STRUCTURED data sources... in ONE call.' It distinguishes itself from siblings by explicitly noting 'this is NOT open-web search' and by naming ask_pipeworx as an alternative for different use cases.

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

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

Explicit guidance is provided: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also gives a prerequisite ('ACCOUNT REQUIRED') and a fallback if not signed in, plus depth-tier guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns top-N tools with names, descriptions, and full input schemas (with curated examples), and each result is 'ready to call directly' with no second schema lookup. This tells the agent what to expect from the response and that no additional round-trips are needed. It does not contradict annotations.

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

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

The description is three sentences, front-loaded with purpose and usage, and each sentence earns its place. The long domain list is arguably necessary to convey the tool's scope. No filler or redundancy—it is concise yet informative.

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 what the tool does, when to use it, and what it returns. It includes return format details (top-N, schemas, examples) and the 'call this FIRST' heuristic. Given the tool is read-only, idempotent, has a rich schema, and no output schema, the description is complete enough. It doesn't mention the limit parameter explicitly but that is covered in the 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%: all six parameters (query, q, task, limit, search, description) are documented with descriptions. The description adds minimal parameter meaning by saying 'describing the data or task' which maps to the query parameter, but it doesn't explain the aliases or the limit constraint beyond what the schema provides. Baseline 3 is appropriate because the schema carries the parameter semantics.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Find tools by describing the data or task.' It enumerates the domains it covers (SEC filings, financials, FDA drugs, etc.) and explicitly distinguishes itself from sibling tools by stating 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This makes the tool's role unambiguous and differentiates it from the many specific-purpose siblings.

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

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

Usage guidance is explicit and actionable: '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...' This tells the agent exactly when to invoke this tool rather than a specific sibling tool. It also implies the alternative: if you already know the specific tool, call it directly. This is strong when-to-use guidance.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description reveals important runtime behaviors: it makes one parallel call across multiple sources, returns specific data fields, includes pipeworx URIs, notes that the USPTO PatentsView API is sunset and 'soft-fails until reactivated', and describes a GDELT→GNews fallback. This is rich behavioral context that annotations do not provide.

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

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

The description is long but densely packed with examples, output components, and fallback behavior. It front-loads with user intents and clearly separates the 'what' from the 'how'. While not terse, every sentence carries meaningful information for a tool with 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?

With no output schema, the description fully enumerates the returned fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and includes details like sorting order, URI format, and fallback behavior. This is complete enough for an agent to know exactly what to expect and how to invoke correctly.

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

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

Schema coverage is 100%, but the description adds examples ('AAPL', '0000320193') and reinforces the zero-padded CIK format. It also clarifies the unsupported name input and references resolve_entity, which goes beyond the raw schema description.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company' and provides numerous example queries ('Tell me about X', 'company profile for Microsoft'). It differentiates from siblings by noting it should be preferred over chaining single-pack lookups and that resolve_entity should be used for name-based requests.

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

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

Explicit when-to-use guidance is given: use when the user asks for a holistic view of a company, and explicitly says to prefer it over chaining single-source lookups. It also provides a clear exclusion: names are not supported, and directs users to resolve_entity first if only a name is available.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the 'clear sensitive data' use case but does not disclose additional behavior beyond deletion. It is consistent with annotations, 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?

Two sentences, front-loaded with the primary action, and no unnecessary words. Every phrase earns its place.

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

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

For a simple single-parameter tool with no output schema and adequate annotations, the description covers purpose, usage, and relationships completely. No critical context 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 coverage is 100% for the single 'key' parameter, which is described as 'Memory key to delete'. The description's 'by key' adds no new semantic detail, so baseline 3 applies.

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

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

The description explicitly states 'Delete a previously stored memory by key', giving a specific verb and resource. It also distinguishes from siblings by referencing 'remember and recall', clarifying its role in the memory lifecycle.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with remember and recall, indicating complementary relationships.

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 explains the full behavior beyond annotations: it fetches the page, extracts title/description/key links, outputs standard llms.txt markdown, and returns a single text blob. Since there is no output schema, this is valuable context. Annotations confirm read-only, open-world, idempotent behavior; the description adds the actual processing steps and output format 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 four sentences, front-loaded with the main action, and each sentence adds value: what it does, how it works, output format, and use cases. No redundant or filler content.

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

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

Given the simple two-parameter schema and no output schema, the description covers everything an agent needs: input URL, optional max_links, processing behavior, output format, and practical use cases. It is complete for both selection and invocation.

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 url and max_links already well documented. The description adds slight context (e.g., 'key links' implies what max_links counts) but does not significantly extend the schema's meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's verb and resource: 'Generate a production-ready llms.txt file for any URL'. It specifies the exact purpose (indexing by AI crawlers) and distinguishes it from sibling tools like scan_competitor_ai_presence by focusing on producing the llms.txt file itself.

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

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

The description explicitly lists three concrete use cases: getting a client's site indexed, drafting your own llms.txt, and auditing a competitor's site. This gives clear context on when to use the tool, though it does not name alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: only the caller's subscriptions are returned, only active ones by default, and it outlines the exact return fields. No contradictions with annotations.

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

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

Two clear, front-loaded sentences with no redundant information. Every word adds value: purpose, scope, returned fields, and usage guidance.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It covers return fields, default behavior (active only), and the intended workflow, making it easy for an agent to invoke and interpret results 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% for the single optional parameter include_inactive, which is well-documented in the schema. The description does not add extra semantics about the parameter, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe/unsubscribe by being a read-only listing operation, and it explicitly lists return fields.

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

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

It provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke it (before subscribing, when needing an id to cancel), though it doesn't explicitly name alternative tools or when not to use it.

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

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

Beyond the annotations, the description discloses practical behavioral traits: 'Rate-limited to 5 per identifier per day', 'Free; doesn't count against your tool-call quota', and 'The team reads digests daily and signal directly affects roadmap.' It also clarifies the limitation of not being able to fix other servers' tools, which is useful context. 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 thorough yet each sentence serves a distinct purpose: purpose, when-to-use, exclusion, formatting, and operational details. It is front-loaded with the core purpose and then provides necessary details without redundancy. No fluff.

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

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

The tool has only 3 parameters with no output schema, and the description covers all essential aspects: what to report, when to use it, boundaries (Pipeworx only), formatting rules, and rate limits. It is complete enough for an agent to decide and invoke correctly without additional questions.

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 extensive descriptions for all parameters (100% coverage), including the enum values and field-level details. The description adds extra guidance on message composition: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which supplements the schema's message description. This is a modest but meaningful enhancement, so it earns 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 a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It directly explains the tool's purpose and distinguishes it from sibling research/subscription tools by naming specific feedback categories (bug, feature/data_gap, praise).

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

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

It explicitly states when to use the tool ('Use when a tool returns wrong/stale data...') and provides a firm 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 goes beyond a simple context statement and gives actionable 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 adds valuable behavioral context beyond the annotations: it mentions the data source (CF analytics-engine), privacy (no PII), output shape (pack, tool, count), and caching behavior (5min-1h). This gives the agent a clear picture of what to expect without contradicting the readOnly/openWorld/idempotent hints.

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

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

The description is well-structured: a hook, the return values, use cases, and technical notes. Every sentence adds information, and it is front-loaded with the core purpose. No wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description is remarkably complete. It covers what is returned, why it is useful, data sourcing, privacy, and caching. The agent has everything needed to decide whether to use it and what to expect.

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

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

Schema description coverage is 100%, so the schema already fully explains the window parameter, including the meaning of shorter vs longer windows. The description's mention of windows adds no additional semantic value, 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 what the tool does: it returns trending AI agent calls on Pipeworx, including top tools, packs, and call volume. It uses a specific verb and resource, and distinct output content, distinguishing it from sibling tools like discover_tools or recent_alerts.

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

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

The 'Useful for' section provides three concrete use cases, giving clear context on when to use this tool. It also explains the trade-off between window lengths. However, it does not explicitly mention alternative tools or when not to use it, so it falls slightly short of a perfect score.

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?

Far beyond the readOnly/idempotent annotations, the description discloses thresholds (3pp deviation, 0.30 Jaccard similarity, 20% placeholder filter), the fill-check logic with realizable_edge_pp, the 'do not trade it' condition, and behavioral quirks like skipped_low_similarity. There is no contradiction with the annotations.

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

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

The description is long but well-structured with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and high information density. Every sentence conveys a distinct behavior, though it could be trimmed slightly without losing meaning.

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

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

With no output schema, the description fully enumerates response fields (`opportunities[]`, `partition_check{}`, `gap_pp`, etc.) and explains edge cases such as placeholders_filtered, thin_legs[], and the condition where realizable_edge_pp ≤ 0. It also provides pointers to a related tool for custom sizing, making the usage envelope 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?

Although the schema already provides 100% parameter coverage, the description enriches both `event` and `topic` with concrete examples, mode-specific behavior, and a no-argument mode for trending_scan. It explains what happens inside each mode (walking child markets, partition_check, cross-event flattening) beyond the simple schema text.

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 arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' – a specific verb and resource. It then distinguishes three call modes (no-arg trending_scan, `event`, and `topic`), each with distinct behavior, and differentiates itself from siblings like polymarket_fill_risk by directing custom sizing there.

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: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It recommends `event` for a specific market, explains the trade-off of cross-event scanning, and explicitly names an alternative tool for custom sizing.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses significant behavioral traits: 1-hour KV-level caching, per-leg slippage subtraction, half-Kelly cap at 0.25, the 24h-move warning, segment-specific gate relaxations (Run 8), and the diagnostics/funnel counters explaining empty segments. It also flags the unreliability of the Fed EFFR signal without paid data. This fully contextualizes the tool's runtime behavior.

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

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

The description is front-loaded with the core purpose and then organized into clearly labeled segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, response top-level, knobs). It is dense, but every sentence adds product or behavior detail. It could be shortened for quicker scanning, but the structure aids comprehension.

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

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

For a tool with no output schema, the description provides a remarkably complete picture: it enumerates the three response segments, the per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), the top-level diagnostics, and the reasons segments may be empty. It also covers caching and the reliability caveat for Fed data, making it sufficient for an agent to set expectations 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?

The schema already has 100% parameter coverage with detailed descriptions. The tool description adds extra context by grouping parameters as 'TRADEABLE-EDGE KNOBS' and explaining the interplay (e.g., min_partition_leg_kelly compensates for min_kelly not applying to basket trades). This adds meaning beyond the schema, though the schema alone is already strong.

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

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

The description opens with a clear verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly frames the use case ('what should I bet on today') and distinguishes the tool from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement and a curated segment breakdown.

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

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

The description provides strong context: it is built for spotting bet opportunities without manual market browsing, and it explains when the output will be sparse (e.g., Fed bets excluded, concentrated longshot rare-by-design). However, it does not explicitly name alternative tools for cases like cross-exchange arbitrage, so it stops short of a full when-to-use/when-not-to-use matrix.

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

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

Beyond the readOnly/idempotent annotations, the description discloses significant behaviors: the 60-day snapshot TTL, snapshot gaps on cache-miss, decay computed from daily closes (not intraday), the signed edge_pp_net convention (negative = SELL YES), and the distinction between tracked and expired opportunities. This is rich operational context.

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

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

The description is dense but organized with 'Args:', 'RESPONSE:', and 'LIMITS:' sections that make scanning easy. Every sentence conveys essential information, front-loading the core question it answers. For a tool with no output schema, this level of detail is warranted and not wasteful.

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

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

Given the tool's time-series complexity, two optional params, no output schema, and rich annotations, the description compensates fully by explaining the response structure (tracked, expired, snapshot_dates), field semantics (trend, decay_pp_per_day), and data limitations (TTL, cache-miss gaps). It is a complete usage guide.

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 (100% coverage). The description restates defaults and clamps but adds no new semantic beyond what the schema provides. Baseline 3 is appropriate since 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 uses a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers a distinct question ('how long has this edge existed and is it shrinking?') and differentiates from sibling tools like polymarket_edges by focusing on time-series decay rather than current edge values.

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

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

The description implies when to use the tool by contrasting fresh vs. stale edges and mentioning it works from daily snapshots. It does not explicitly name alternative tools or state exclusions, but the sibling list and context make its role clear. A named alternative would push this to 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?

While annotations declare readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral detail: it 'walks the ladder,' returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), and discloses the risk of partial fills converting arb into unhedged directional positions. This goes well beyond annotation hints and does not contradict them.

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

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

The description is long, but it is well-structured with clear SINGLE-MARKET and BASKET sections and front-loaded with the core purpose. Every sentence serves a purpose, though the length could deter quick scanning. It earns its place given the tool's complexity.

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

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

With no output schema and complex return data, the description thoroughly enumerates outputs (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; basket-specific fields like capture_ratio, thin_legs, forced_directional_risk). It also covers prerequisites, defaults, and risk scenarios, making it virtually complete for safe invocation.

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%, yet the description adds critical semantics beyond property descriptions: it explains that size_usd means max spend on buys vs target proceeds on sells in single-market mode, and settlement notional (shares per leg) in basket mode. It also clarifies side defaults for each mode, enriching the schema.

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

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

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

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

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

The description explicitly states when to use this tool: '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 risk of partial basket fills, providing clear before/after context.

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

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

Beyond annotations (read-only, idempotent), the description discloses rich behavioral details: the meaning of compatibility_warning, why skipped_cross_type/subtype counters exist, how temporal_alignment affects spread validity, and that the delta is only a real signal when bet shapes are equivalent. This gives the agent a deep understanding of edge cases and failure modes, far exceeding the annotation baseline.

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

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

The description is dense and long, but front-loaded with the core purpose and structured into clear sections (modes, response, safety fields). Every sentence adds value for a complex tool; however, a few phrases could be tightened (e.g., the parenthetical example in skipped_cross_type) without losing meaning.

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

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

With no output schema, the description fully compensates by explaining the response structure, including the two compatibility_warning scenarios, temporal alignment fields, and skipped-cross counters. It covers all critical aspects of the tool's behavior, making it self-sufficient for an agent to understand inputs, outputs, and caveats.

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

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

While schema coverage is 100%, the description adds substantial meaning: it lists the exact 'topic' enum values, explains that explicit parameters override the topic mapping, and describes the response semantics (raw probabilities, spread calculation, top_spreads_pp). This elevates parameter understanding well 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 a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes the tool from siblings by focusing on cross-venue comparison and explicitly details two operating modes (topic shortcuts vs. explicit ticker/slug), leaving no ambiguity about its 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 provides explicit usage context, including when to use each mode, how the 'topic' shortcuts work, and critically warns that 'pre-mapped ≠ tradeable' and that most pre-mapped topics return compatibility_warning. It also explains conditions under which the tool's output is not meaningful (non-equivalent bet shapes, temporal misalignment), effectively telling the user when NOT to rely on the result.

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 bar is lower. The description adds valuable behavioral context beyond those: the key-omission listing behavior and scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID). It does not describe the return format or error handling, which is a minor gap.

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 then expands with usage examples, scoping, and sibling tool references. Every sentence provides necessary context 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?

The tool is simple (one optional parameter, no output schema) with rich annotations. The description covers purpose, usage scenarios, scoping, and relationships to sibling tools, making it fully sufficient for an agent to select and invoke the tool correctly. No critical information 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 description coverage is 100% for the single 'key' parameter, and both the schema and description note the omission behavior. The description adds no new detail beyond the schema, 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 uses a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and explicitly contrasts with sibling tools 'remember' and 'forget', making its purpose unambiguous and distinct. It also clarifies the dual-mode behavior (list all keys when key omitted), which further disambiguates the tool.

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 use cases ('the user's target ticker, an address, prior research notes') and explains when to use it ('without re-deriving it from scratch'). It explicitly pairs with 'remember' to save and 'forget' to delete, establishing clear when-to-use/not-to-use boundaries relative to alternatives.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses key behaviors: the optional mark_read:true flag changes read state, affecting subsequent calls, and events carry specific fields (source, citation_uri, raw payload). This adds crucial context not in annotations, despite a subtle interplay with readOnlyHint that is clarified by the description.

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

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

The description is concise (two sentences) and front-loaded with the primary purpose. The second sentence packs substantial information about payload, filtering, mark_read, polling, and an alternative endpoint, which is dense but organized effectively. Every sentence earns its place; no filler.

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

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

Given the tool's moderate complexity (5 optional parameters, no output schema) and strong annotations, the description covers all essential usage aspects: return format, filtering options, state-changing behavior (mark_read), polling suitability, and the HTTP alternative. It is sufficiently complete for an agent to invoke correctly without further clarification.

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

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

The schema already covers all parameters, providing a baseline of 3. The description adds value by explaining filtering with type and since, and explicitly describing mark_read's effect on future calls. This enriches understanding beyond the schema's dry descriptions, though the schema's coverage remains robust.

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 "Pull[s] fired events from your subscription feed," identifying the resource (subscription feed) and specific action (pull requested events). It distinguishes itself from siblings by detailing the feed's provenance and filtering options, making it unique among the provided sibling 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 mentions that "Polls work fine" and that the same feed is accessible via a direct HTTP endpoint for scripts/dashboards, providing clear usage context and an alternative. However, it does not explicitly name sibling tools or state when not to use this tool versus another, leaving some room for ambiguity.

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 hints. The description adds substantial behavioral context: fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail due to PatentsView sunset, and the returned changes[] structure with citation URIs. This goes well 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 dense with useful information — query examples, source behavior, parameter formats, return shape, and alternative tool — in a single paragraph. It is longer than minimal but every clause adds value; no filler or tautology.

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

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

With no output schema, the description carries the burden of explaining return values, and it does: "structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs." It also covers multiple data sources, fallback behavior, and sunset risks, making the tool's behavior fully understandable.

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

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

Schema coverage is 100% and describes each parameter. The description adds value by explaining `since` accepted formats (ISO vs relative) with concrete examples and recommending '30d'/'1m' for monitoring, plus example ticker/CIK values. This is helpful but not drastically beyond schema.

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

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

The description clearly identifies a specific verb+resource: "change feed for a company in the last N days" with single parallel call. It distinguishes from entity_profile (static profile) and other siblings like recent_alerts by naming the alternative explicitly.

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

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

Provides explicit when-to-use context via natural-language query examples and states the alternative: "Use entity_profile instead when you want the static profile... regardless of window." Also gives practical parameter guidance (typical '30d' or '1m' for monitoring).

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 key behavioral traits: storage as a key-value pair scoped by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. This adds meaningful context about data lifecycle that annotations do not convey.

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

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

The description is three sentences long, front-loaded with the primary purpose, and contains no fluff. Every sentence adds value: purpose, usage scenarios, storage details, and pairing with related tools.

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

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

For a simple two-parameter tool with no output schema, the description fully covers the purpose, when to use it, storage behavior, and complementary tools. It provides all necessary context for an agent to correctly invoke and understand the tool.

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

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

The input schema already provides 100% coverage with clear descriptions for key and value. The description adds examples of what to store (e.g., 'resolved ticker') but does not introduce new parameter semantics beyond what the schema already explains, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse, using the specific verb 'save' and identifying the resource as data (key-value pairs). It distinguishes itself from the siblings recall and forget by explicitly pairing with them, making its unique role 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?

It gives explicit when-to-use guidance: 'Use when you discover something worth carrying forward' and provides concrete examples (resolved ticker, target address, user preference). It also names the alternatives for retrieval and deletion (recall and forget), clarifying the intended workflow.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral context: it reveals internal cascade through multiple lookup endpoints ('replaces 2-3 manual lookups'), auto-disambiguation, and specific data source behavior (SEC EDGAR for companies, RxNorm for drugs). This goes well beyond the structured annotation fields.

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

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

The description is well-structured and information-dense: it opens with natural-language triggers, includes a bold directive, and breaks down the two entity types in a clear, bullet-like fashion. Every sentence contributes new, actionable information without redundancy or padding.

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 and absence of an output schema, the description is remarkably complete. It specifies exact return values (ticker, 10-digit CIK, company_name; RxCUI, ingredient, brand), citation URIs, and the full range of accepted inputs for both entity types. This provides an agent with all necessary information 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?

The schema already covers both parameters with 100% coverage, including enum values for 'type' and examples for 'value'. The description enhances this by explaining accepted input formats ('ticker, CIK, or company name' / 'brand or generic name'), output fields per type, and the auto-disambiguation behavior. This earns a score above the baseline 3.

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

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

The description explicitly defines the tool's purpose: resolving a user-spoken name to the canonical official identifier required by other tools. It provides multiple natural-language examples ('What's the ticker for…', 'find the CIK for…') and clearly distinguishes the two supported entity types (company, drug). This also separates it from sibling tools such as entity_profile or compare_entities by focusing on identifier lookup.

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: 'Use FIRST whenever you have a name but need an ID.' It also details the supported types and the return values for each, making the usage context clear. However, it does not explicitly state when not to use the tool or name alternative tools for exclusion, so it stops short of a perfect 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds value by disclosing that the tool probes each entity with ai_visibility_check, ranks results, and returns a list with score, confidence, and signal density. This is useful behavioral context beyond the annotations.

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

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

The description is four sentences, each serving a distinct purpose: defining the comparison, explaining the mechanism, giving a use case, and stating the return format. No fluff or redundancy.

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

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

Despite the tool's moderate complexity, the description covers purpose, mechanism, use case, and return format. Combined with the full schema and annotations (read-only, idempotent), it provides sufficient context for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with each parameter clearly documented (e.g., entities has description of first-as-subject). The description reinforces the entities parameter and mentions the internal ai_visibility_check call, but does not add significant meaning beyond the schema. Baseline 3 applies.

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

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

The description clearly states the tool's function: compare AI visibility across multiple entities side-by-side using ai_visibility_check, ranking by score. It distinguishes itself from the sibling ai_visibility_check by emphasizing multi-entity comparison and competitive auditing.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example query, making it clear when to use this tool. It implies a comparison over single-entity checks, though it does not explicitly name alternatives or when-not-to-use scenarios.

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

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

Beyond the readOnly/idempotent annotations, the description discloses partial failure behavior, the 5-30s first-measurement delay from bundlephobia, and the sources_failed field indicating timeouts. It also explains what data is aggregated and how results are returned, providing rich behavioral context.

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

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

The description is dense but well-structured, leading with purpose, then usage, return format, ecosystem limitation, and failure behavior. No wasted sentences; every part adds necessary detail for correct tool use.

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

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

With no output schema, the description compensates by listing the exact summary fields, per-advisory details, links, and alternative versions. It also covers edge cases like timeouts and partial failures, making the tool's behavior fully understandable for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the package parameter is NPM-only and that version defaults to the latest, plus how version may affect the returned alternative versions. The NPM ecosystem constraint is meaningful beyond the schema's generic 'npm package name'.

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

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

The description clearly states it is a composite 'should I add this npm package' check in one call, specifically fanning out across deps.dev and bundlephobia. It distinguishes itself from sibling tools like scan_competitor_ai_presence by describing its unique aggregate behavior and NPM-only scope.

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 whenever an agent asks 'is X safe / popular / small' or what adding a package costs, and provides a clear exclusion: for other ecosystems (PyPI, Maven, etc.) use deps.dev:version directly. This gives strong when-to-use vs alternative guidance.

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

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

Despite annotations already declaring readOnly/idempotent hints, the description adds significant behavioral context: it explains the truncation behavior ('cap is 200K chars (longer inputs are truncated and flagged)'), the embedding model (BGE-base-en), chunking (500-char overlapping windows), and that outputs include character offsets for verbatim verification. 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 a single dense paragraph that front-loads the core purpose and then adds relevant details (when to use, pairs with, technical cap). Every sentence contributes meaningful information without fluff. It is appropriately sized for the tool's complexity.

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

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

Even though there is no output schema, the description explicitly states what the tool returns: 'top-N passages with character offsets and similarity scores.' It also covers edge cases (truncation flag) and parameter limits (limit 1-20, default 5). Given the tool's moderate complexity, the description is remarkably complete.

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

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

Schema coverage is 100%, but the description enriches parameter meaning with concrete examples: 'text' is contextualized as 'the text you already pulled (e.g. a SEC 10-K body, an article, a long tool result)', and 'query' is exemplified with 'supply-chain risk', 'fiscal year 2024 revenue'. This adds practical understanding beyond the bare schema.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record.' It uses a specific verb+resource (search inside a record) and distinguishes itself from sibling tools like ask_pipeworx_grounded by explicitly noting it operates on already-fetched text and returns passages with offsets for verification.

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

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

The description explicitly states when to use this tool: 'Use when the record is too big to cram into the prompt — search_within saves context...' It also provides an alternative and integration path: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This is clear, actionable guidance.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds transparency by specifying the exact output (Google search volume, keyword difficulty, CPC, competition) and the 10-keyword limit, which is useful for an agent. It does not contradict annotations or introduce misleading claims.

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 exceptionally concise: two sentences and an example. It front-loads the core metrics and keyword limit, then provides a practical usage example. No wasteful words or redundant 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?

Since there is no output schema, the description appropriately lists the return fields (volume, difficulty, CPC, competition) and the 10-keyword cap. It doesn't mention error handling or the API source (DataForSEO), but the schema covers the API key and defaults, making this adequate for the tool's complexity.

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

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

The schema provides 100% description coverage for all 4 parameters, including the default location_code and API key format. The description's example mirrors the schema without adding deeper semantic meaning, so it merely meets the baseline for high coverage.

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

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

The description clearly states the tool's function: it returns monthly search volume, keyword difficulty (0-100), CPC, and competition for up to 10 keywords at once. The phrase 'Keyword research for SEO' and the example invocation distinguish it from the sibling tools (e.g., ai_visibility_check, bet_research), which are not keyword-focused.

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

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

The description implies its use case via 'Keyword research for SEO' and provides a concrete example call with parameters (keywords, location_code, _apiKey). However, it doesn't explicitly state when to prefer this tool over others or mention exclusions, so it falls 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?

Goes beyond annotations by adding important behavioral constraints: OAuth requirement, phone verification and 10/day SMS cap, webhook auto-disable after 10 consecutive failures, and one-time return of webhook signing secret. These details meaningfully inform an agent about side effects and limitations.

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

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

The description is front-loaded with core purpose and then supplies detailed but structured lists of types and delivery options. While quite lengthy, every sentence contributes useful information and maintains clarity for a complex subscription API.

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

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

Given the complexity (nested params, multiple types, delivery options) and lack of an output schema, the description covers prerequisites, return value, delivery channels, rate limits, and webhook behavior. It's sufficiently complete for an agent to understand how to invoke it and what to expect.

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

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

Schema already covers all parameters with examples (100% coverage), so baseline is 3. The description adds semantic context on top, such as explaining that items:['5.02'] indicates officer change and that polymarket_edge detects cross-venue mispricings, and clarifies the always-on feed vs optional delivery. This adds value beyond schema.

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

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

The description clearly states the tool's function with a specific verb ('Create') and resource ('a proactive monitoring subscription to a live-data event stream'), and distinguishes it from read/list or unsubscribe siblings by emphasizing subscription creation and return of a new subscription 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?

Provides clear context for when to use the tool (proactive monitoring), explicit prerequisites (Pipeworx OAuth account required; anonymous/BYO cannot persist), and details supported subscription types and delivery channels. However, it doesn't explicitly name alternative tools or state when not to use, so slightly below 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 the tool as readOnly, idempotent, and openWorld, and the description adds behavioral context beyond those: it returns category-bucketed examples, is drawn from a 'live catalog of thousands of tools,' and includes the exact tool and argument shape for each. It does not contradict the annotations, and given the annotation coverage, the added context is 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 a single dense paragraph but front-loads example questions and flows logically from purpose to usage. It earns its length by covering multiple aspects (examples, return content, invocation modes, when to use) without fluff. Slightly long but 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?

For a tool with no required parameters and no output schema, the description is complete: it explains what the tool returns, how to invoke it, what the `topic` parameter does, and when it should be used. It also mentions the live catalog source, giving the agent enough context to decide and call it correctly.

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

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

The input schema already documents the `topic` parameter with its allowed values (finance, pharma, etc.) and the omit-for-full-spread behavior at 100% coverage. The description repeats these details and adds a few examples ('finance', 'pharma', 'betting') but no additional semantic information beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: it returns category-bucketed example questions with the exact tool and argument shape that answers each, and positions itself as 'the onboarding entry point for an agent that just connected.' This specific verb+resource description distinguishes it from siblings like discover_tools and ask_pipeworx.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools,' providing clear timing relative to other tools. It also explains the two invocation modes (no arguments for full spread, topic for focus). However, it does not explicitly mention when not to use it, though 'FIRST' implies priority.

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?

It discloses that the row is deactivated, not deleted, which is a key behavioral trait not present in the annotations. It also explains ownership enforcement and the impact on recent_alerts. This adds valuable context beyond the annotations.

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

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

The description is three sentences, front-loaded with the core action. Every sentence earns its place: action, ownership constraint, and post-cancel behavior. No unnecessary words.

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

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

For a single-parameter tool with no output schema, the description is complete. It covers ownership, side effects (deactivation), and how history remains accessible via recent_alerts. Annotations already cover safety, so no further detail is needed.

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

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

The schema description covers the parameter fully, stating 'Subscription id (uuid) returned by subscribe.' The tool description adds no new parameter details beyond 'by id,' which is already in the schema. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It specifies the resource (subscription) and the operation (cancel), distinguishing it from sibling tools like subscribe and list_subscriptions. The ownership enforcement adds a precise scope.

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

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

The description gives clear context about how to use the tool: you can only cancel your own subscriptions, and the id is required. It also points to recent_alerts for historical events, hinting at alternative usage. However, it does not explicitly state when not to use or list alternative 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 readOnly/openWorld/idempotent annotations, the description discloses significant behavioral details: the exact routing logic (SEC EDGAR + XBRL with percent-delta math vs grounded pipeline), the return structure (verdict types, citation, reasoning), and that it replaces 4-6 sequential calls. This gives the agent a strong mental model of what happens when 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 dense and information-rich, but the opening sentence is a long list of trigger phrases that delays the core purpose. It is appropriately sized for the complexity (routing, verdicts, replacement of calls), with no unnecessary fluff. Slightly verbose structure prevents a 5.

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

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

Despite having no output schema, the description fully explains what the tool returns (verdict with five enumerated values, actual value with pipeworx:// citation, reasoning). It also covers routing, tolerance handling, and efficiency gains. The tool has simple parameters and annotations, so the description provides complete context for callers.

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 descriptions for both parameters (claim and tolerance_pct) with examples, ranges, and defaults. The tool description does not add significant parameter-level meaning beyond what the schema states. Since schema coverage is 100%, the baseline of 3 applies; the description's mention of 'exact percent-delta math' is only indirectly related to parameter semantics.

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

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

The description explicitly states the tool's function: natural-language claim verification against authoritative sources. It provides trigger phrases, distinguishes between company-financial claims (SEC EDGAR/XBRL path) and other claims (grounded pipeline), and clearly differentiates from sibling tools by focusing on fact-checking with a verdict output.

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

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

The description gives clear when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing decision between financial and non-financial claims. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, so it falls just short of a 5.

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