Medlineplus

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds valuable context beyond annotations: default model is free, using Anthropic requires a BYO API key with direct payment, and it discloses the return structure. This covers cost/auth implications and response format.

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: first states the action and output, second explains defaults and API key, third lists use cases. Every sentence earns its place, information is front-loaded, and there is no redundant filler.

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

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

For a moderately complex tool with no output schema, the description covers the return values (per-model score/confidence/signals/raw_response + combined view) and payment/auth requirements. Combined with 100% schema coverage and strong annotations, the description is complete for an agent to select and invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the cost implications of the _apiKey parameter and clarifying the default behavior of the models parameter. It helps an agent decide how to set parameters effectively.

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

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

The description uses a specific verb ('Probe') and resource ('one or more LLMs') with a clear outcome (score visibility 0-100 per model). It clearly distinguishes from siblings by focusing on AI visibility scoring, and even provides example use cases.

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

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

The description states clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that imply when to use this tool. It does not explicitly exclude alternatives or name conflicting sibling tools, but the context is strong enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral context beyond these: it 'fills arguments,' returns structured answers with 'stable pipeworx:// citation URIs,' works 'on every tier, one fast call,' and implies a limitation by contrasting with ask_pipeworx_grounded's 'hallucination-resistant single answer with verbatim evidence + confidence.' 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 longer than average but front-loads the critical instruction and packs every sentence with actionable guidance. The structure flows from preference, to use cases, to operational details, to escalations and examples. While slightly verbose, the examples earn their place for a default tool.

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

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

Given the tool's complexity as a router to 5,462 tools, the description is remarkably complete: it covers purpose, trigger phrases, alternatives, examples, behavioral guarantees (citations, speed), and tier availability. It does not describe the exact return schema, but no output schema exists, and the description's mention of 'structured answer with citation URIs' suffices 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% and all six parameters are aliases for 'question,' fully described in the input schema. The description provides example questions, but these echo the schema's own examples and add no new parameter-level semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Routes the question to the right one of 5,462 tools across 1419 verified sources, returns the structured answer with stable pipeworx:// citation URIs.' It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH for questions about current or historical data' and 'Use whenever the user asks "what is", "look up", "find", "get the latest", "how much", "current", or any factual question.' It also explicitly says 'START HERE for most questions' and 'Step up only when needed' with named alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds meaningful context beyond that: the beta status, live candidate testing, the current inactive state (retired on 2026-07-26), and the clarification that it is a full working router rather than a fallback. This gives the agent insight into the experimental behavior without contradicting annotations.

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

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

The description is four sentences, each contributing to the beta-versus-stable distinction. It includes specific details (tool count, date of retirement) that are useful for trust calibration but not strictly necessary. It remains reasonably concise and front-loaded with the core identity.

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, but the description references the same response shape as ask_pipeworx, which is adequate given the sibling tool. It also covers the current operational state and fallback behavior, making the tool's usage context complete for an agent deciding between beta and stable.

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

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

Schema description coverage is 100%, with all six parameters being aliases for the single required 'question' parameter. The description adds no parameter-specific meaning, but the schema already fully documents the aliases and purpose. Baseline 3 is appropriate since the structured data carries the semantic burden.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, an identical universal router with the same 5,462 tools, arguments, and response shape. It distinguishes itself as the experimental edge and explicitly frames its purpose: to test candidate routing improvements. This is specific and separates it from the stable sibling 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?

Explicitly states when to use: 'when you want the newest routing' and directs to use it exactly like ask_pipeworx. It also notes results are compared against the stable router, implying the stable tool is the alternative for production use. This provides clear context and an implicit when-not-to-use scenario.

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by detailing the exact return shape (answer, evidence, confidence, source, fetched_at, refusal_reason), listing specific refusal reasons (not_in_source, no_tool_match, etc.), and disclosing 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 purpose, then efficiently explains the mechanism, return format, usage scenarios, and cost tradeoff. Every sentence adds value, and the structure is logical and easy to parse. Length is justified by the tool's complexity.

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

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

Despite lacking an output schema, the description fully specifies the success and failure return values, including refusal reasons. It also provides enough context about the routing system and when to use the tool, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% and all six parameters are aliases for 'question,' which the schema already documents. The description does not add additional parameter-level semantics beyond the general routing behavior. Baseline of 3 is appropriate since the schema carries the full burden.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and explains its mechanism: it routes through the same system as ask_pipeworx, fetches data, and extracts the answer only from the tool result. This distinguishes it from siblings like ask_pipeworx (casual mode) and ask_pipeworx_beta while giving a specific verb+resource+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?

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' This clearly states when to use this tool and when to use an alternative, along with the cost tradeoff.

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 (readOnlyHint, idempotentHint, destructiveHint=false) already indicate a safe read operation. The description goes far beyond by disclosing fan-out behavior, resolver confidence (market_match_confidence), short-circuit statuses (low_confidence_match, market_closed_or_inactive), wide-spread illiquidity handling, and resolution-rule risk with specific refund scenarios. This is exceptional transparency.

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

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

The description is long but tightly structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It front-loads a one-sentence summary and then provides dense, necessary detail. Every section contributes to safe and correct usage; trimming it would risk losing critical information.

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

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

Despite having no output schema, the description fully specifies input formats, classification categories, fan-out logic, response shapes, resolver contract, parent-event extraction, news fallback fields, safety mechanisms, and resolution-rule edge cases. This is a model of completeness for a complex data-aggregation 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 the baseline is 3. The description adds practical examples for the 'market' parameter (slug, URL, question text) and clarifies the output size trade-off for include_raw. However, it does not elaborate on the 'depth' parameter beyond the schema, though the fan-out examples implicitly illustrate thorough behavior. Overall, it adds useful context beyond the raw schema.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from siblings like ask_pipeworx (general Q&A) or polymarket_arbitrage by focusing on bet-specific data aggregation and classification. The intended input formats and output highlights are immediately stated.

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 the intended use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives concrete fan-out examples across multiple categories. However, it does not mention when not to use this tool or name specific alternatives, so it stops short of the top 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?

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description details data sources (SEC EDGAR/XBRL, FAERS), specific metrics per type, handling of off-calendar fiscal years, sorting by primary metric, and output with paired data and citation URIs. This substantially enriches the agent's understanding of 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 structured for quick parsing: trigger phrases first, then core purpose, then priority instruction, then type-specific details, then sorting and output. It is dense but every sentence adds value without redundancy.

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

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

For a tool with no output schema, the description covers the key aspects: range of entity counts (2–5), entity types, data sources, metrics, sorting, and output format (paired data + citation URIs). It also contextualizes the tool's efficiency ('Replaces 8–15 sequential lookups'), making it complete for the agent to select and use correctly.

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

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

Even though schema coverage is 100%, the description adds significant meaning: it explains that type='company' pulls specific financial data from 10-K filings and type='drug' pulls adverse-event counts, and clarifies that values are 2–5 tickers/CIKs or drug names with examples. This goes well beyond the schema's short 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 explicit trigger phrases and clearly defines the tool as 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from siblings by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups,' which separates it from entity_profile and similar 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?

Usage guidance is explicit: it lists trigger phrases like 'X vs Y' and 'rank these companies,' and instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This tells the agent exactly when to invoke this tool and when not to (instead of sequential lookups).

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 clear. The description adds no extra behavioral context (e.g., behavior on unmapped codes, rate limits, or language handling) but is consistent with the annotations. It neither contradicts nor enriches the annotation-provided information.

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 sentence, front-loaded with the core purpose, and contains no unnecessary words. It is extremely concise while conveying the essential functionality.

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 presence of an output schema, the description needn't explain return values. It covers the main mapping function and the schema covers parameter details. It lacks mention of edge cases or language-specific behavior, but for a straightforward mapping tool with good annotations and schema, this is adequately 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 descriptions cover 100% of parameters, including the list of allowed code systems and the lang options. The description duplicates some of this information (e.g., code system list) but adds no new parameter semantics beyond what the schema already provides. Since schema coverage is high, 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 function: mapping specific clinical code systems (ICD-10-CM, SNOMED CT, etc.) to MedlinePlus consumer-health topics. The verb 'Map' is specific and the resource is well-defined, distinguishing it from sibling tools like resolve_entity or compare_entities.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. It simply states what the tool does without mentioning scenarios or alternative tools, leaving the agent without decision support.

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 latency expectations (15-60s, up to ~90s), account tier requirements, the findings-packet structure (gaps[], contradictions[]), citation fetching guarantees, and semantic excerpting. It also warns against inventing answers, adding trust-relevant behavioral detail.

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

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

The description is dense and front-loaded with the critical account requirement, and each paragraph covers a distinct topic (use case, alternatives, depth mechanics, citations, latency). It's longer than average but every sentence contributes; only slight trimming could improve scannability.

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

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

Given there is no output schema, the description thoroughly explains expected return data: evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and excerpting behavior. It also covers account constraints and performance, making the tool's behavior well-understood.

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

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

Although the schema already covers question and depth with descriptions, the description elaborates on depth semantics (quick/standard/thorough facet counts, gap-recovery hops, contradictions scan, paid tier) and notes that broad/multi-part questions are acceptable. This adds practical meaning beyond the schema, though the schema already had a good baseline.

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

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

The description clearly defines deep_research as grounded multi-source research across 1,419 structured data sources, decomposing questions and routing them in parallel. It explicitly contrasts itself with open-web search and with ask_pipeworx, making its purpose unique among 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?

It provides explicit usage guidance: best for broad/multi-part structured questions, single lookups should use ask_pipeworx, breaking/current-news topics should prefer ask_pipeworx, and unsigned users should use ask_pipeworx. This directly addresses when to use deep_research vs alternatives.

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

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

Annotations already cover safety (read-only, idempotent). The description adds valuable behavioral context: returns top-N tools with full schemas and curated examples, ready to call directly without a second lookup. It also advises calling this first, which is an ordering behavior not captured in annotations.

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

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

Three sentences, front-loaded with purpose, and the domain list is packed but not wasteful. Every sentence contributes essential information.

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

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

Description explains what the tool returns, when to use it, and the breadth of domains. No output schema is needed because the description clearly states the response format. Sufficient for a discovery tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the query is a natural language description but doesn't need to add more since the schema already explains aliases and limits.

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

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

Description clearly states the tool's function: 'Find tools by describing the data or task.' It distinguishes from sibling tools by positioning itself as the first stop to see the option set, rather than retrieving specific data.

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

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

Explicitly says when to use: '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 provides clear guidance and differentiates from alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond by detailing the fan-out across multiple sources, specific return fields (CIK, recent_filings, fundamentals, patents, news, LEI), and notable failure modes: 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated' and 'GDELT→GNews fallback.' This gives the agent essential behavioral expectations 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 a single dense paragraph, front-loaded with natural-language examples and then expanding into structured output details. It packs a lot of useful information—input format, return fields, fallback chains, and limitations—so every sentence earns its place. However, the length and run-on structure slightly reduce scannability; a bulleted breakdown would improve readability while retaining 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 tool's complexity (multi-source fan-out, multiple return types, no output schema), the description is remarkably complete. It explains what the tool does, when to prefer it (holistic requests), what it returns (CIK, filings, fundamentals, patents, news, LEI), how to pass input (ticker/CIK), what limitations exist (names not supported, patents sunset), and how failures are handled (soft-fail, fallback). This fully equips 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 descriptions already cover 100% of parameters (type enum with description, value description including ticker/CIK and name restriction). The description adds valuable illustrative examples ('AAPL', '0000320193'), clarifies the zero-padding requirement, and reinforces the name unsupported rule in context. While the schema is already thorough, the description enriches understanding with concrete usage patterns.

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

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

The description begins with multiple user-phrased queries ('Tell me about X', 'research Acme', 'brief me on Tesla') and states the core action: 'full cross-source profile of a US public company in ONE parallel call.' It clearly identifies the resource (US public company) and the output (profile across SEC/XBRL/news/etc.), distinguishing it from more targeted tools by emphasizing holistic coverage.

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

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

Explicit guidance is given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when NOT to use it: names are not supported, and instructs to 'use resolve_entity first if you only have a name.' This provides clear usage context and alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' is not new information. It does add the context that it clears 'previously stored' data, implying it only affects existing memories, but this is a minor extension 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 short sentences that front-load the core action, then usage guidance, then sibling context. Every sentence adds value, with no redundancy or fluff.

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

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

For a simple one-parameter delete tool with annotations covering safety and idempotency, the description fully covers the primary purpose, usage scenarios, and relationship to sibling tools. No output schema is needed, and no further context is required for an agent to invoke it correctly.

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

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

The input schema has 100% coverage with a clear description for the 'key' parameter ('Memory key to delete'). The description only repeats 'by key', adding no additional semantics beyond what the schema already provides.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' It explicitly names the resource (memory) and the method (delete by key), and distinguishes itself from siblings by mentioning pairing with remember and recall, which are complementary functions.

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 guidance on when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also implicitly contrasts with alternatives by referencing remember and recall as companions, making the decision 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details beyond these annotations: it fetches the page, extracts specific elements, and emits a text blob in llms.txt markdown format. This clarifies the tool's internal process and output 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 three sentences, front-loaded with the primary action, then process details, then use cases. Every sentence contributes meaningful information with no redundancy or filler. It is well-structured and appropriately sized.

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 2 parameters, no output schema, and simple readOnly/idempotent behavior, the description is fairly complete. It covers input (URL), process (fetch and extract), output (single text blob), and scenarios. Minor gaps like failure handling or rate limits are not addressed, but they are less critical given the tool's simplicity and annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond the schema; it mentions 'URL' generically and does not explain 'max_links' behavior. However, the schema already documents both parameters clearly, so the description adds minimal extra value here.

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: generating a production-ready llms.txt file for any URL. It specifies the verb 'Generate', the resource ('llms.txt file'), and the scope ('for any URL'), making it easily distinguishable from sibling tools that focus on auditing or checking AI visibility.

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: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context for when to use the tool, though it does not name alternative tools or explicitly 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 (readOnlyHint=true, destructiveHint=false) already establish safety. The description adds context by specifying the return fields and that it lists only active subscriptions by default, which aligns with the include_inactive parameter. It goes beyond the annotations by explaining the practical use case, though it doesn't detail pagination or authorization requirements. This is adequate for a shallow read-only tool.

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, each serving a distinct purpose: stating the action, listing return fields, and providing usage guidance. There is no redundant or filler content. Information is front-loaded with the tool's core function.

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, low complexity. The description covers the key behavioral aspects (what it lists, what fields return, when to use it). Since there is no output schema, listing the fields compensates for that gap. The description is fully sufficient for an agent to invoke the tool correctly without further clarification.

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

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

Schema coverage is 100% for the single parameter, so the baseline is 3. The description mentions 'active subscriptions' which hints at the default behavior of include_inactive, but this is already captured by the schema description ('Include cancelled subscriptions... default false'). No additional semantic meaning is added beyond the schema.

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

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

The description starts with a clear verb+resource combination: 'List the caller's active subscriptions.' It specifies the scope (caller's own subscriptions) and distinguishes this from sibling tools like subscribe and unsubscribe by focusing on listing. The explicit enumeration of returned fields further reinforces the purpose.

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

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

The third sentence provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool and why, directly contrasting with subscribe/unsubscribe alternatives. It clearly implies when it is appropriate rather than the mutation 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?

All annotations are false/neutral, so the description carries full burden. It adds practical behavior: rate-limited to 5 per identifier per day, free, doesn't count against quota, team reads digests daily. This goes beyond annotations without contradicting them.

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

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

Though ~10 sentences, every sentence serves a purpose: purpose, scope, exclusions, content guidance, and operational limits. It is front-loaded with the core action and efficiently structured for quick 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 simple feedback tool with no output schema, the description fully covers what it does, when to use it, what pitfalls to avoid, and operational constraints. An agent can confidently decide and invoke this tool without additional context.

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

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

Schema already documents all 3 parameters at 100% coverage. The description adds crucial usage nuance: don't paste end-user prompt, describe in terms of Pipeworx tools/packs, and message should be specific. This enriches the schema definitions meaningfully.

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 tool sends feedback to the Pipeworx team about broken, missing, or desired functionality. It explicitly distinguishes from sibling tools by defining its role as the feedback channel for this connection, not a general-purpose 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 provides explicit when-to-use guidance (bug, feature gap, praise) and when-not-to-use (tool from another MCP server). It also instructs how to frame feedback in terms of Pipeworx tools/packs, which is essential for correct usage.

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

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

Beyond the strong annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable behavioral context: it is self-aggregating, derived from CF analytics-engine, contains no PII, returns only (pack, tool, count), and has caching behavior (5min-1h). This fully discloses the operational characteristics.

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

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

The description is well-structured with a clear opening statement, numbered use cases, and a concise final line about the data signal. It is slightly longer than minimal but every sentence contributes substantive information. The front-loading of the core purpose is effective.

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

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

With no output schema, the description compensates by explaining the return content (top tools, top packs, total call volume, and the tuple format), the data source, caching, and privacy. It also covers the parameter's semantics and usage scenarios, making it fully sufficient 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?

The schema fully documents the 'window' parameter with an enum and description. The tool description adds interpretive meaning ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), which goes beyond the schema. A 4 is appropriate because the schema already provides strong coverage and the description enriches it without redundancy.

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

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

The description clearly identifies the tool's function: reporting what other AI agents are calling on Pipeworx, with specific outputs (top tools, top packs, total call volume). It uses an active verb ('returns') and names the resource ('Pipeworx'), and the use cases distinguish it from sibling tools like discover_tools or search.

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

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

The description provides explicit use cases (discovering hot data sources, confirming canonical tools, checking alignment) and explains how the window parameter affects interpretation. It does not explicitly name alternative tools or state when not to use it, so it falls short of a 5, but the guidance is clear and practical.

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 well beyond the annotations by detailing internal logic: partition_check sum deviations >3pp emit a signal, semantic anchor with ≥0.30 Jaccard similarity, placeholder filter with >20% threshold returning null, and fill check behavior (theoretical vs realizable edge). No contradictions with annotations.

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

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

The description is dense but well-structured: opens with a clear summary, then uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize complex details. Every sentence contributes critical information without redundancy.

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

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

For a complex tool with no output schema, it fully describes response fields (opportunities[], partition_check), edge cases (placeholder fractions, thin_legs), and actionable warnings (realizable_edge_pp ≤ 0). It also points to a companion tool for sizing, making the description self-sufficient.

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

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

Although schema coverage is 100%, the description adds substantial context: for `event` it explains walking child markets and partitions; for `topic` it explains cross-event scanning and similarity constraints. This deeply enriches 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?

Description states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', clearly identifying the tool's function and method. It distinguishes three modes (trending_scan, event, topic) and is differentiated from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance is provided: 'Call with NO args for a trending_scan... pass event for... topic for...' with recommendations ('event (recommended for a specific market)', 'topic (for cross-event scanning)'). Also mentions exclusions: 'realizable_edge_pp ≤ 0 means ... do not trade it' and alternative tool 'For custom sizing use polymarket_fill_risk'.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description goes far beyond this by detailing the three segments, the diagnostics funnel, the 24h-move warning, the Fed note, the caching behavior, and the special handling of partition_overround (kelly_fraction_half=0 at parent level). It also explains that edge is net of slippage and Kelly is capped. There is no contradiction.

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

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

The description is long but highly structured with clear section markers: model families, response top-level, diagnostics, knobs, and caching. Every sentence conveys essential information—no fluff. The front-loading of purpose makes it immediately scannable.

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 takes on the burden of explaining return values, which it does thoroughly: by_segment keys, per-opportunity fields (edge_pp_net, kelly_fraction, etc.), diagnostics structure, and the Fed note. The 9-parameter tool is fully contextualized with rationale for each knob and the caveats around the models.

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 substantial meaning. It explains the tradeable-edge knobs (min_liquidity, max_spread_pp), the interplay with min_kelly for partitions, the behavior of slippage_pp (Polymarket zero fees, typical 20-50bp), and why partition_overround ignores min_kelly by design. This richly augments the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes this tool from siblings like polymarket_arbitrage by explaining the three model families and the stated purpose ('what should I bet on today'). The scope and unique value proposition are explicit.

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

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

The description gives strong context: it is built for discovering betting opportunities without paging hundreds of markets, and it mentions tradeable-edge knobs that help filter results. However, it does not explicitly contrast itself with alternatives or state when not to use it (e.g., for focused single-market analysis). This is clear context, but lacks direct exclusions.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds substantial context: history depth bounded by 60-day TTL, decay computed from daily closes not intraday, snapshot gap meaning, and detailed response semantics. No contradictions.

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

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

Description is long but well-structured with labeled sections (Args, RESPONSE, LIMITS). Every sentence earns its place, adding valuable detail without redundancy. The main purpose is front-loaded in the first sentence.

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 thoroughly documents the response structure (tracked, expired, snapshot_dates), their fields, and even caveats like history depth and decay calculation method. This is complete for a complex telemetry tool with no other schema support.

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

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

Schema covers both parameters completely with defaults and constraints (days clamp 2-30, window enum 24hr/1wk/1mo). The description repeats the same information without adding new meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

Clearly states it provides edge persistence and decay telemetry built from daily polymarket_edges snapshots, answering a specific question about edge age and shrinkage. This distinguishes it from siblings like polymarket_edges, which likely provides current edges rather than historical persistence.

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?

Implies usage for evaluating whether an edge is stale or decaying, contrasting fresh vs 3-week-old edges and referring to median lifespan as a competition clock. Does not explicitly name alternatives or exclusions, but the context makes it clear when to use it.

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

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

Annotations already declare read-only and idempotent, but the description adds rich behavioral detail: it walks the order-book ladder, returns specific fields, explains the meaning of size_usd in different modes, and discloses that partial basket fills convert an arb into an unhedged directional position. This goes far beyond the annotations and provides essential risk context.

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

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

The description is long but every sentence earns its place. It uses clear structural markers (SINGLE-MARKET, BASKET) and bolded key terms, making it scannable despite its density. It is not padded with fluff; all content is directly useful for tool invocation.

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 carries the burden of explaining return values. It lists all key output fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, etc.) and even names the failure mode (forced_directional_risk). This is a complete picture for the agent.

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

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

The schema covers 100% of parameters, but the description adds significant meaning beyond the schema. For example, it explains that size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode, and clarifies side defaults. This gives the agent a deeper understanding of how to set parameters for each mode.

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 from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill-risk assessment rather than opportunity discovery or execution.

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

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

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

Despite annotations already declaring readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds rich behavioral context: compatibility_warning triggers, temporal_alignment meaning, skipped_cross_type/subtype counters, and why spreads can be meaningless. No contradiction with annotations.

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

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

The description is long but highly structured and every sentence delivers critical information. The first sentence states purpose, then modes, then response format, then safety fields. It's dense but not redundant. Slightly overlong, but the complexity of the tool justifies the length.

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

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

With no output schema, the description fully explains the return value: leg-by-leg prices, matched spread[].top_spreads_pp, and safety fields. It also addresses edge cases (matched_pairs:0, temporal_alignment:false) making it complete for a complex tool with 3 optional params and no output schema.

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

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

Schema already covers 100% of parameters, but the description adds substantial semantics beyond the schema: it explains the interplay between topic, kalshi_event_ticker, and polymarket_event_slug (overrides), defines the valid topic values, and clarifies what explicit tickers look like. This goes well beyond the baseline of 3.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly specifying the verb (cross-venue spread) and the resources (Kalshi and Polymarket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison, not intra-venue arbitrage.

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 explains two usage modes (topic and explicit ticker/slug) and provides strong guidance on when to trust the spread. It includes warnings about pre-mapped topics not being tradeable and when compatibility_warning triggers. However, it never names alternative tools for cases where it's not appropriate, so it lacks explicit exclusions or alternative recommendations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description supplements this by revealing scoping details ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the behavior of omitting the key argument to list all keys. It adds useful context beyond annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds value: action, use case, and scoping/pairing. There is no redundant phrasing or unnecessary detail.

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

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

For a simple read-only memory tool with one optional parameter, full schema coverage, and safety annotations, the description covers all essential aspects: how to retrieve, how to list, scoping, and relationship to sibling tools. No output schema exists, but the tool's behavior is simple enough that return values are predictable; the description is complete for 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% with a clear parameter description ('Memory key to retrieve (omit to list all keys)'). The description adds illustrative examples of valid keys (user's target ticker, address, prior research notes) and explains the parameter's role in the remember/recall/forget lifecycle, enriching the schema's baseline.

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

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

The description states a clear verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It explicitly distinguishes from sibling tools by naming remember and forget, and provides concrete use examples (target ticker, address, research notes). This is a specific, actionable 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 gives clear context for when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with remember and forget, implying complementary alternatives. However, it does not explicitly state when not to use the tool or list other alternative tools for exclusion, so it lacks full when-not guidance.

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

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

The description states that mark_read:true flags events as read and changes future results, which is a stateful side effect. This directly contradicts the annotations readOnlyHint=true and idempotentHint=true, as the tool can mutate read state. Annotation contradiction is present.

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

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

Three sentences deliver the core purpose, return payload structure, filter options, side-effect behavior, and an external endpoint. The information is dense but not verbose, with every clause earning 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?

Without an output schema, the description explains the return fields (source, citation_uri, raw payload), covers all parameter behaviors, and discloses the mark_read side effect. It also addresses polling and script access, making it nearly complete for a read-oriented tool.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds examples (e.g., 'sec_8k') and clarifies semantics (since = fired_at >= time), but these are minor additions beyond the schema baseline.

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

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

The description clearly states the tool 'pulls fired events' from a subscription feed, with a specific resource and action. It is distinguished from sibling tools like list_subscriptions and recent_changes by focusing on the persisted alert feed and the evaluator-written events.

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 context for when to use it ('Polls work fine') and provides an alternative access method (HTTP URL for scripts/dashboards). However, it does not explicitly contrast with sibling tools or state when not to use it, so it slightly misses the highest bar for explicit 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?

Beyond the annotations (readOnly, idempotent), the description discloses fan-out to multiple external APIs, GDELT→GNews fallback on rate limit/5xx, and USPTO soft-fail due to PatentsView sunset. It also describes the return structure (changes[] grouped by source plus total count), providing rich behavioral context that annotations do not cover.

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

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

The description is compact but dense, front-loading purpose with example queries. All sentences carry essential information, but the single long paragraph with embedded clauses could be more scannable with bullet points. 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?

Given the tool's complexity (3 data sources, fallback logic, parameter formats), the description provides sufficient detail for correct invocation. It covers return format, parameter semantics, explicit alternative tool, and even notes the PatentsView sunset. No output schema is present, but the description compensates by describing the return structure.

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

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

The input schema already covers all 3 parameters with descriptions, but the description adds practical examples for `since` (ISO/relative formats, suggested '30d'/'1m') and clarifies how the window applies to each data source. This adds value beyond the schema, though `value` and `type` are not further elaborated.

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 provides a change feed for a company over a recent time window, listing specific sources (SEC, GDELT/GNews, USPTO) and explicitly contrasting with entity_profile. This distinguishes it from sibling tools like recent_alerts and entity_profile, demonstrating a specific verb+resource+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?

It provides natural language query examples ('What's new with X', 'latest on Y') and explicitly directs users to entity_profile for static profiles, giving clear when-to-use vs alternative guidance. This goes beyond implied usage by naming the alternative and the scenario for choosing 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 annotations, the description discloses key-value scoping per identifier, persistence differences between authenticated and anonymous sessions, and a 24-hour retention window. These details add meaningful context about data lifecycle and access, which annotations only hint at.

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

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

Four sentences, front-loaded with the primary action, and every sentence adds value: purpose, usage examples, storage scoping, retention policy, and related tools. 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?

Given the tool's simplicity (2 required params, no output schema) and strong annotations, the description covers all necessary aspects: what it does, when to use it, how data is scoped/permitted, and how it relates to recall/forget. It is complete 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 description coverage is 100%, so the baseline is 3. The description does not meaningfully elaborate on the parameters beyond calling it a key-value pair; the schema already provides clear examples for key and value.

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

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

The description clearly states the tool saves data for later reuse, using a specific verb and resource. It distinguishes itself from siblings recall and forget by explicitly positioning itself as the store operation, making its purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. It also mentions pairing with recall and forget, which clarifies the complementary tool usage without needing to consult sibling descriptions.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context: internal cascading through lookup endpoints, auto-disambiguation, and return fields (ticker, CIK, company_name, citation URI, RxCUI, ingredient, brand). This exceeds what annotations provide, though not exhaustive (no rate limits or error 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 dense but well-structured with a clear opening phrase and organized supported types. It front-loads the core use case and provides useful details. It is somewhat long but every sentence contributes value, so it earns a 4 rather than a 3.

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 no output schema, so the description compensates by describing return values and citation URIs. It also explains the internal cascade and auto-disambiguation. It lacks edge-case handling or permission requirements, but for a read-only lookup tool, it is sufficiently complete given the annotations.

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

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

Schema coverage is 100% with parameter descriptions. The description enhances this with type-specific examples ('ozempic', 'metformin'), alias handling (ticker, CIK, or company name), and 'auto-disambiguated', which adds meaning beyond the schema's raw type definitions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers required by other tools, with explicit examples ('ticker', 'CIK', 'RxCUI'). It distinguishes itself from siblings by emphasizing it's a lookup/resolution step for IDs, not a search or profiling 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 a clear trigger: 'Use FIRST whenever you have a name but need an ID.' It also explains it replaces 2-3 manual lookups. However, it does not explicitly mention alternatives or when not to use it, hence not a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it makes multiple probes via ai_visibility_check, ranks results, and returns specific fields (score, confidence, signal density). This provides useful behavioral context beyond the safety annotations, though it doesn't mention potential rate limits or error handling.

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 with information densely packed and front-loaded: purpose, behavior, use case, and return format. Every sentence earns its place with no redundancy or filler.

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

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

The tool has no output schema, but the description explicitly lists return fields ('ranked list with score, confidence, signal density per entity'). Parameters are fully explained in the schema, and the description provides the overarching workflow. It could mention the optional models parameter, but that is documented in the schema, so completeness is solid but not maximal.

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

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

Schema coverage is 100% and the schema already describes the 'entities' parameter including the first-entry-as-subject detail. The description does not add parameter-level semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states it 'Compare[s] AI visibility across multiple entities side-by-side' and 'Probes each entity with ai_visibility_check, ranks by score'. The verb+resource is specific and distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on AI presence ranking.

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: 'Useful for competitive AI-marketing audits' with an example query. It implies when to use (multi-entity comparison) but does not explicitly name alternatives or state when not to use, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds significant behavioral context: it fans out to multiple sources, handles partial failures gracefully, notes potential 5-30s delay on first bundlephobia measurement, and mentions the sources_failed field. This goes well 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 longer than average but information-dense: purpose, usage, return fields, ecosystem limitation, and failure behavior are all present without padding. It is front-loaded with the core purpose. Slightly long but justified for a composite tool.

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

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

Given the tool's complexity and lack of an output schema, the description fully compensates by enumerating the summary fields, per-advisory details, links, alternative versions, and partial failure behavior. It covers ecosystem scope and timeout considerations, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% for both parameters (package and version), so the schema already explains their meaning. The description does not add further parameter semantics beyond what is in the schema, meriting the baseline score of 3.

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

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

The description opens with a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call' and clearly names the sources (deps.dev, bundlephobia) and the result fields. This unambiguously distinguishes it from sibling tools, which cover different research and monitoring tasks.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also states the NPM-only scope and directs other ecosystems to 'deps.dev:version directly', giving clear when-to-use and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the database scope (MedlinePlus/NLM) but does not disclose other behavioral traits such as pagination, result ordering, or potential limitations. This is comparable to a basic read operation with some context, but not rich.

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, concise sentence that is front-loaded with the key verb and object. It is free of redundancy and delivers maximum meaning in minimal space.

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, the presence of an output schema, and comprehensive annotations, the description is largely complete. It conveys the core function and scope, though it omits any usage guidance or mention of default behaviors, which are partially covered by annotations and 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 75% with descriptions for 'db', 'limit', and 'retstart'. The description adds minimal parameter context beyond what the schema provides, only implying that 'query' is a free-text search term. This does not significantly enhance schema understanding.

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

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

The description clearly states a specific action ('Free-text search') and resource ('MedlinePlus topics (or related NLM databases)'). It is not a tautology and gives enough detail to understand the tool's scope, though it does not explicitly distinguish itself from sibling tools like 'search_within'.

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 no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or comparisons to sibling search tools, leaving the agent to infer usage context.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses specific technical behavior: the use of BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K character cap with truncation flagged, and the return format with offsets and similarity scores. This adds significant transparency about how the tool operates.

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, then usage guidance, then technical details. Every sentence adds distinct value with no redundancy or filler, making it appropriately concise for the wealth of information it conveys.

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 must explain return values, and it does: 'top-N passages with character offsets and similarity scores.' It also covers edge cases (truncation at 200K chars) and the relationship with ask_pipeworx_grounded, making the description complete for this tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by giving concrete examples (SEC 10-K body, article) and clarifying that 'text' is a previously pulled record. It also explains 'limit' through 'top-N passages' and provides query examples, making the parameter semantics richer.

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

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

The description states a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from sibling tools by emphasizing 'inside' and positioning itself as a tool for large fetched records, contrasting with the broader 'search' sibling. It also names the output (top-N passages with character offsets and similarity scores), making the purpose unambiguous.

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

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

Explicit guidance is given: 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded.' This tells the agent exactly when to choose this tool and how it relates to an alternative, fulfilling the when-to-use and comparison requirement.

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

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

Annotations already cover idempotency and non-read-only nature. The description adds valuable behavioral details: OAuth account requirement, feed always-on vs optional email/sms, phone verification requirement, and per-day SMS cap. These go beyond the schema and annotations, though webhook specifics are left to the schema.

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 informative, with every clause earning its place. It front-loads the core purpose and then structures details by supported types and delivery channels. While longer than ideal, the complexity justifies the length; it is 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?

For a subscription-creation tool with nested objects and multiple types, the description covers purpose, requirements, type-specific parameters, delivery options, and return value. It does not cover webhook behavior in the top-level text, but the schema delivers that. Missing error handling or idempotency details are partially covered by annotations, making this quite 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. The description enriches parameter meaning with concrete examples for each subscription type (e.g., items:['5.02'] for officer change, topic:'fed' for polymarket_edge) and clarifies delivery channel semantics beyond the schema's already detailed 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 begins with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly differentiates from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by framing this as the creation action, and explicitly notes it returns the 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 strong context on when to use: creating subscriptions to various event streams. It gives prerequisites (OAuth required) and implies alternatives by contrast with siblings, but does not explicitly state 'use list_subscriptions to view existing' or 'use unsubscribe to remove.' Still, the usage context is clear and actionable.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, which the description complements by detailing the return structure: category-bucketed example questions with exact tool + argument shape. It also discloses the optional `topic` parameter's effect and the source (live catalog). 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 a single dense paragraph that packs a lot of information. It is front-loaded with example questions and includes all necessary usage details. While not overly verbose, it could be tightened slightly, but every sentence contributes value. Therefore it earns a 4.

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

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

With only one optional parameter and no output schema, the description fully explains what to expect: category-bucketed questions, each with the tool and argument shape. It covers usage for both the no-argument full spread and focused topic queries, and places it in the workflow with 'use FIRST'. This is complete for the tool's purpose.

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 for `topic` has 100% coverage, listing the enum values. The description adds practical examples (finance, pharma, betting) and clarifies that omitting it yields a cross-category spread, which is not in the schema. This goes slightly beyond the schema, making the parameter semantics clearer.

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 onboarding entry point that returns category-bucketed example questions and explains the tool's scope. It distinguishes itself from siblings by naming it as the go-to for learning what Pipeworx can do and how to call meta-tools. The specific verb+resource+scope (suggest questions for Pipeworx onboarding) makes it unmistakable.

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

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

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools. This provides clear when-to-use guidance. It also explains that omitting `topic` gives a full spread and passing `topic` focuses the results, making the usage context complete.

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: ownership enforcement, deactivation instead of deletion, and the preservation of historical events via recent_alerts. This complements the annotation hints (non-read-only, non-destructive, idempotent) and gives the agent a clear picture of side effects.

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 action. Every sentence provides meaningful information without unnecessary detail.

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 parameter, no output schema) and the presence of annotations, the description covers all essential aspects: purpose, usage constraint, and behavior. It is fully sufficient for the 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?

The input schema already provides 100% coverage for the single parameter 'id' with a clear description. The tool description adds no further parameter-specific semantics, 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 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on the cancellation action.

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 useful context about ownership enforcement and the deactivation behavior, which helps the agent understand when to use the tool. However, it does not explicitly compare to alternatives like list_subscriptions or subscribe.

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, openWorld, idempotent), the description discloses significant behavioral details: the dual-path routing (SEC EDGAR + XBRL fast path vs grounded pipeline), the exact verdict set (confirmed / approximately_correct / refuted / inconclusive / unsupported), and the inclusion of verbatim evidence with citations. This goes well beyond the annotations' minimal safety hints.

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

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

The description is long but information-dense. It leads with immediately recognizable examples, then progresses logically through purpose, usage, routing, output, and efficiency. Every sentence contributes meaningful detail, though a slight trim could improve scannability without losing substance.

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

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

Given there is no output schema, the description fully explains return values (verdict, actual value with citation, reasoning). It also covers the two major execution paths and the tolerance parameter. The description is comprehensive enough for an agent to know exactly what to expect and how to invoke the tool correctly.

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

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

Schema coverage is 100% for both parameters (claim and tolerance_pct). The description adds value beyond the schema by explaining how tolerance_pct overrides claim wording, suggesting 1–2% for hallucination detection, and stating the default cap of 5%. This is actionable parameter guidance not present in the schema.

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

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

The description opens with explicit natural-language triggers and states the core function: "natural-language claim verification against authoritative sources." It also distinguishes the tool from siblings by noting it "Replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison)." This is a specific verb+resource+scope with clear differentiation.

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

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

The description clearly states when to use it: "Use whenever the agent needs to check whether something a user said is factually correct." It also gives concrete routing guidance (SEC EDGAR for financial claims, grounded pipeline for other claims). However, it does not explicitly name alternative tools or state when NOT to use this tool, so it lacks explicit exclusions/alternatives.

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