Wikipathways

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

Annotations already convey read-only and non-destructive behavior. The description adds value by disclosing the cost model (free default vs. BYO Anthropic key), default model selection, and return structure (per-model and combined view). It does not cover rate limits or failure modes, but the annotation hints cover the safety profile well.

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 five sentences with zero waste. Purpose is front-loaded, followed by default behavior, optional model usage, return format, and use cases. Every sentence earns its place.

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

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

Despite lacking an output schema, the description explicitly lists the return fields (score, confidence, signals, raw_response per model, plus combined view). All 4 parameters are explained in the description or schema. The typical workflow (choosing models, providing API key) is covered, making the tool self-contained for an agent.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds contextual nuance (e.g., who pays for Anthropic calls) but does not substantially enhance understanding beyond the schema. This matches the baseline for high-coverage schemas.

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

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

The description uses specific verbs ('probe', 'score') and clearly identifies the resource (LLMs for business/brand/product/topic visibility). It distinguishes from sibling tools by focusing on AI visibility scoring across multiple models, with explicit use cases for AI-marketing audits and competitive monitoring.

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

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

The description provides clear usage contexts (AI-marketing audits, pre-launch brand checks, competitive monitoring) and dictates when to use the default free model vs. Anthropic with BYO key. However, it lacks explicit 'when not to use' comparisons with sibling tools like deep_research or compare_entities, which would strengthen guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond annotations: it routes to 5,529 tools, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is a single fast call. No contradictions.

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

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

The description is lengthy but front-loaded with the imperative 'PREFER OVER WEB SEARCH' and then supported by concrete examples and alternative tool guidance. Every sentence contributes to usage understanding, though some may be redundant for a simple routing tool. It remains structured and 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?

For a router tool with no output schema, the description explains the return format (structured answer with citation URIs), specifies it's the default entry point, works on every tier, and contrasts with sibling tools for different use cases. It does not mention error handling or ambiguity resolution, but the strong usage guidance compensates.

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 same 'question' field. The description itself adds little parameter-specific detail beyond what the schema already provides, though it does clarify that the tool 'fills arguments' for downstream tools. This meets the baseline expected for high schema coverage.

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

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

The description clearly states a specific verb and resource: 'PREFER OVER WEB SEARCH for questions about current or historical data' and 'Routes the question to the right one of 5,529 tools across 1455 verified sources'. It explicitly distinguishes 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: 'Use whenever the user asks...' with concrete example phrasings and domain categories. It also states when not to use it ('Step up only when needed') and names exact alternative tools (ask_pipeworx_grounded, deep_research) with conditions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the bar is lower. The description adds valuable context beyond annotations: it explains the beta/experimental nature, that candidate routing improvements are enabled live only when under test, that currently no candidate is active and it matches ask_pipeworx exactly, and that it is not a fallback but a full router.

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 distinct information: identity and live improvement behavior, current inactive state, usage guidance, and reinforcement that it is a full working router. It is dense but not bloated; no filler or repetition.

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 one required parameter, no output schema, and the description references 'same response shape' as ask_pipeworx while giving current-state and usage context. It is sufficient for an agent to select and invoke it, though a brief example or fuller explanation of 'universal router' would make it fully self-contained.

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

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

Schema coverage is 100%: all six parameters are explicitly described as aliases for the single 'question' parameter. The description adds no new parameter-level information beyond stating 'same arguments' as ask_pipeworx, so the baseline of 3 is appropriate.

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

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

The description clearly identifies it as a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape, while distinguishing it from the stable ask_pipeworx as the experimental edge. It specifically states 'Use it exactly like ask_pipeworx' and 'this IS a full working router', 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?

The description explicitly specifies when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names the alternative (ask_pipeworx) and provides context that results are compared against the stable router, plus notes the current state with no active candidate.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses refusal reasons, the exact return structure, the constraint of using only tool-result content, and the extra LLM call cost. This gives the agent a precise behavioral model 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 moderately long but each sentence delivers distinct value: purpose, mechanism, return format, refusal reasons, usage scenarios, and cost comparison. It is front-loaded with the primary purpose, though it could be slightly tightened without losing information.

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

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

For a complex tool routing across 5,529 tools and 1,455 sources, the description fully explains return values, refusal modes, and limitations (data_truncated, tool_error). It also covers when to use this mode versus the lighter alternative, making it sufficient for correct invocation.

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

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

Schema description coverage is 100% — the schema already documents the question parameter and its aliases. The description adds little parameter-level detail beyond implying the question is natural language and used for routing, which is a marginal enhancement over the schema.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, explicitly contrasting it with ask_pipeworx. It states the core behavior: extracts answers using only tool-result content and returns evidence, which distinguishes it from siblings.

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

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

Explicit when-to-use guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on... prefer ask_pipeworx for casual lookups.' It also names the alternative (ask_pipeworx) and notes the cost trade-off, giving unambiguous selection criteria.

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

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

Annotations already indicate readOnly, idempotent, openWorld, non-destructive. The description goes far beyond by detailing resolution logic, classifier fan-outs, response shapes, edge-case handling (low-confidence, closed markets, wide spreads), and cancellation-rule parsing. It fully discloses behavioral traits like 'low-confidence resolutions short-circuit' and 'closed/dead markets...return status:"market_closed_or_inactive". 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 comprehensive but overly long. It front-loads the purpose but then dives into extensive lists (classifiers, fan-out examples, response shapes, resolver contract) that could be summarized or structured more concisely. While it uses section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), the length may overwhelm an AI agent. Many sentences are necessary given the tool's complexity, but some redundancy and excessive detail reduce conciseness.

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

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

The description is exceptionally complete, covering all critical aspects: input types, resolution confidence, market states (active, closed, low-confidence), liquidity warnings, cancellation-rule risk, parent-event extraction, news fallback handling, and output structure. Without an output schema, the description fully informs the agent of what to expect and how to interpret results. No gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds examples for the 'market' parameter and some context for 'depth' and 'include_raw', but these are already explained in the schema. The extra detail about fan-outs and classifiers is useful for understanding the tool's behavior but does not add new meaning to the parameters themselves beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison), making it distinct from sibling tools like 'polymarket_edges' or 'ask_pipeworx'. The verb 'Research' combined with specific resource 'Polymarket bet' and the detailed fan-out examples leaves no ambiguity.

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

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

The description provides explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It is clear when to use the tool, but it does not explicitly state when not to use it or mention alternatives to the tool. This prevents a score of 5, but the provided context is strong enough for a 4.

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

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

Annotations already declare the tool safe (readOnlyHint, idempotentHint, not destructive). The description adds valuable behavioral details: results sorted by primary metric, off-calendar fiscal year handling, citation URIs returned. 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 concise at ~120 words, front-loaded with actionable examples, and every sentence provides essential information without redundancy. It is well-structured, covering purpose, usage, parameters, and behavior efficiently.

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

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

Given the simple parameter set (2 params, no output schema), the description fully covers what the tool returns (paired data + citation URIs), how data is sorted, and the data sources. No gaps remain for effective tool selection and invocation.

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

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

The description adds significant meaning beyond the schema: for 'type=company' it specifies pulling latest 10-K revenue, net income, cash, long-term debt; for 'type=drug' it lists FAERS adverse events, FDA approval counts, active trial counts. This enriches the parameter documentation even though schema coverage is 100%.

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 specifies a very clear purpose: side-by-side comparison of 2-5 companies or drugs in one call. It uses explicit example queries (e.g., 'X vs Y', 'which is bigger') and distinguishes from siblings by stating it replaces 8-15 sequential lookups, contrasting with a single-entity tool like entity_profile.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It covers both when to use (comparison queries, ranking) and what each entity type does (company financials, drug regulatory data), effectively contextualizing against siblings.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds rich behavioral context: decomposition into facets, parallel routing to 5,529 tools, return packet with verbatim evidence and gaps[], contradictions[] scanning for standard/thorough, semantic excerpting of large records, citation_uri resolution, latency expectations, and account tier restrictions. Nothing contradicts the annotations.

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

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

The description is long but densely packed with essential information, front-loaded with the account prerequisite and core function. Every sentence adds value—alternatives, depth behavior, citation guarantees, excerpting, latency, and limitations—so the length is justified and well-structured.

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

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

Given the tool's complexity, no output schema, and rich annotations, the description is remarkably complete. It covers return format (findings packet, evidence, confidence, source, fetched_at, citations), the gaps[] behavior, contradiction detection, hop field, citation_uri semantics, performance expectations, and account/plan constraints—leaving little room for agent uncertainty.

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

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

Though the schema already documents both parameters with 100% coverage, the description adds crucial semantics beyond it: depth is detailed (quick=3 single-hop, standard=5 with gap recovery and contradictions[], thorough=8 paid with full iterative hop), and question examples clarify that natural language and multi-part questions are appropriate. This significantly aids parameter selection.

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

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

The description opens with a clear verb+resource statement: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in ONE call, and explicitly distinguishes itself from open-web search and sibling tools. It also contrasts with ask_pipeworx for single lookups, making its unique role unmistakable.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also explains the depth tiers and states that broad/multi-part questions are its intended use case.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, making the safety profile clear. The description adds that results are 'ready to call directly,' which is useful but not critical. No contradictions.

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

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

The description is front-loaded with the core purpose and efficiently lists domains. It is slightly verbose but every sentence adds value. Could be slightly more concise, but still 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?

For a tool discovery function with 6 parameters (100% schema coverage), no output schema needed, the description fully explains what the tool returns and how to use it. Adequate for its complexity.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description adds context about aliases ('task, q, description, search as aliases') but does not significantly enhance understanding beyond what the schema provides.

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

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

The description starts with 'Find tools by describing the data or task,' which is a specific verb+resource. It lists many domains and distinguishes itself from sibling tools as a discovery tool, not a task-specific 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?

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context on when to use it, though it lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context about patents sunsetting in May 2025 and soft-fail behavior, but does not introduce new safety concerns or contradictions.

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

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

The description is lengthy but well-organized with examples, a clear list of outputs, and important caveats. Every sentence provides value; it earns its length for the complexity of the tool.

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

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

Given no output schema, the description fully details what is returned (cik, company_name, recent_filings with URIs, fundamentals, patents, news via fallback, LEI). No gaps in understanding the tool's capabilities.

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% (both parameters described). The description adds context: type is limited to 'company', value must be ticker or zero-padded CIK (not names), and explains the role of resolve_entity for name resolution. This goes beyond the schema's bare descriptions.

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

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

The description explicitly states the tool provides a full cross-source profile of a US public company, listing multiple query examples and specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It clearly distinguishes from sibling tools like resolve_entity.

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

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

Explicitly advises to prefer this tool over chaining single-source lookups for holistic views, and instructs to use resolve_entity first if only a name is provided. No ambiguity.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description reinforces deletion but adds limited behavioral context beyond stating 'Delete' and 'clear sensitive data.' No contradictions.

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

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

The description is extremely concise, using two sentences to convey purpose, usage context, and complementary tools. Every sentence adds value with no redundancy.

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

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

For a simple tool with one parameter and no output schema, the description is fully adequate. It covers when to use, what it does, and how it relates to siblings.

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

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

The input schema covers the single parameter 'key' with a description. The tool’s description mentions 'by key' but adds no further semantic details beyond what the schema provides.

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

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

The description specifies the verb 'Delete' and the resource 'previously stored memory by key,' clearly indicating the tool's action. It also distinguishes from sibling tools by mentioning pairing with 'remember' and 'recall'.

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

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

The description provides explicit when-to-use scenarios: context is stale, task is done, or clearing sensitive data. It does not explicitly state when not to use or list alternatives, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the actual process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This goes beyond what annotations provide, though it does not detail potential errors or rate limits.

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

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

The description is two sentences and a bullet list, all front-loaded with the core purpose. Every sentence adds value and there is no redundant or extraneous text.

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

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

The description adequately explains the output format (standard llms.txt markdown, single text blob) and mentions key extraction details. Given no output schema, this is sufficient. It could mention assumptions about public URLs or limitations, but overall it is complete for a moderately complex tool with rich 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 reinforces the purpose of the URL and mentions 'maximum number of link entries' in the context of the tool's output, but does not add semantics beyond what the schema already provides for either parameter.

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

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

The description clearly states it generates an llms.txt file for a given URL, targeting AI crawlers. It specifies the verb 'generate' and the resource 'llms.txt file', distinguishing it from related sibling tools like scan_competitor_ai_presence. The use cases are explicitly listed.

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

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

The description provides clear context on when to use the tool, listing three specific use cases (indexing a client's site, drafting for own project, auditing competitors). It does not explicitly state when not to use it or name alternatives, but the sibling list is available for comparison.

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, destructiveHint false. The description adds that it returns specific metadata and a viewer URL, which is useful but does not reveal significant additional behavioral traits beyond what annotations 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?

Two sentences that front-load the main action and output. No wasted words; each sentence adds value.

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

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

For a simple single-parameter retrieval tool with no output schema, the description adequately covers return fields. It is complete enough given the tool's simplicity and annotation richness.

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

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

Schema coverage is 100%, so the schema already documents the 'id' parameter. The description adds an example format ('WP554') but does not significantly extend meaning beyond the schema.

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

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

The description clearly states it retrieves metadata and a viewer link for a single WikiPathways pathway by ID, listing returned fields (name, species, revision, diagram URL). It is specific but does not explicitly distinguish from sibling tools like list_pathways or search_pathways.

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

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

The description implies usage for fetching a known pathway by ID, mentioning 'Keyless' for authentication context, but lacks explicit guidance on when to use this vs alternatives or when not to use it.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, making the safety profile clear. The description adds that the tool is 'Keyless' (no authentication required) and details the return fields (id, name, link, last revision). This provides additional behavioral context beyond annotations.

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

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

The description is three concise sentences with no wasted words. It front-loads the purpose and provides essential details efficiently.

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 lists the exact return fields. Combined with clear parameter info and annotations, it provides a complete picture for a simple list tool. The keyless and single-organism constraints are noted.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds practical examples for organism (e.g., 'Homo sapiens', 'human', 'mouse') and clarifies it accepts common names, which adds meaning beyond the schema's description.

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

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

The description clearly states 'List all WikiPathways pathways for a single organism.' This is a specific verb-resource combination that distinguishes it from related tools like search_pathways, which presumably allow broader or filtered queries.

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

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

The description explains how to set the organism parameter (common or Latin names) but does not explicitly tell when to use this tool versus siblings like search_pathways or get_pathway. It implies usage for listing all pathways for an organism but lacks explicit alternatives or 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 readOnlyHint, idempotentHint, and destructiveHint. The description adds context about the default behavior (active only) and the effect of include_inactive, which goes beyond the schema. 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?

Two sentences, front-loaded with purpose, no wasted words. Efficient and clear.

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

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

For a simple tool with one optional boolean parameter and no output schema, the description covers the purpose, return fields, and use cases completely. Annotations further support completeness.

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 description does not need to add parameter details. The description implies the default (active only) but does not add significant meaning beyond the schema.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the returned fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes itself from sibling tools like subscribe/unsubscribe by specifying its purpose for review and cancellation.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent exactly when to use the tool and what to do with the results.

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?

Although annotations are all false and provide little signal, the description richly discloses behavioral traits: filing returns a claim_token for later lookup, rate-limiting is 5 per identifier per day, it is free and does not count against tool-call quota, and the team reads digests daily. It also explains the asynchronous resolution workflow. This goes well beyond the annotations and gives agents an accurate model of side effects and constraints.

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

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

The description is about 150 words, but every sentence earns its place: purpose, use cases, exclusions, message guidance, token workflow, rate limits, and quota impact. It is front-loaded with the most important information and flows logically. It is not bloated; it is efficiently dense for a tool with this many nuances.

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 covers the tool's behavior: what to report, how to report it, the claim_token retrieval flow, rate limits, and scope boundaries. With nested objects, an enum, and a claim_token follow-up mechanism, the description leaves no significant aspect unexplained. It is complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a valuable message-construction rule not present in the schema ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and contextualizes the claim_token lifecycle in a single workflow. However, most parameter meaning is already perfectly covered by schema descriptions, so the increment is modest but meaningful.

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 'Tell the Pipeworx team something is broken, missing, or needs to exist,' using a specific verb ('tell') and a clear resource (the Pipeworx team). It enumerates concrete use cases (bug, feature, data_gap, praise) and is cleanly distinguished from sibling tools, all of which are research/information tools rather than feedback submission. No ambiguity about what the tool does.

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

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

The description explicitly states when to use the tool (wrong/stale data, missing capability, praise) and when NOT to use it: if the tool came from a different MCP server, file it there instead. It also clarifies the scope ('ONLY for tools served by this Pipeworx connection') and offers a test for uncertainty ('Pipeworx tool names are the ones this connection lists'). This is exemplary usage guidance with clear alternatives and 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 mark readOnlyHint=true, destructiveHint=false, and idempotentHint=true. Description goes beyond by revealing data source (CF analytics-engine), privacy (no PII), aggregation method, and caching duration (5min-1h). No contradictions.

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

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

Three tightly written sentences with no redundancy. Front-loaded with core purpose, followed by use cases, then technical details. Every sentence adds value.

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

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

For a tool with no output schema, the description adequately describes return format ('top tools, top packs, total call volume'). It also covers caching, privacy, and data source, making the tool's behavior fully understandable.

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

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

Schema coverage is 100% with one parameter (window). The description adds semantic value by explaining that shorter windows surface what's hot now while longer windows show steady-state demand, which aids parameter selection beyond the enum values.

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

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

Description clearly states the tool returns trending data: 'top tools, top packs, and total call volume' over a window. This verb+resource combination ('what other AI agents are calling') is specific and distinct from sibling tools like discover_tools or 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?

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tool, checking alignment). While it doesn't state when not to use it or name alternatives, the examples provide clear guidance on appropriate contexts.

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

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

Annotations declare read-only, idempotent, non-destructive. Description adds details on walking child markets, monotonicity checking, partition sum, semantic anchor, partition filter, and fill check against live order book. 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?

Dense with information but slightly verbose; could use bullet points or more structured layout. However, every sentence adds value, and it is front-loaded with the main purpose.

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

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

Given no output schema, the description covers return structure (opportunities array, partition_check, fill check) and references polymarket_fill_risk for custom sizing. Rich enough for an agent to use correctly.

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

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

Both parameters (event, topic) are explained with examples and mode-specific behavior, adding significant meaning beyond the schema descriptions. Schema coverage is 100%, but description enriches it.

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

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

Clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes three modes (no args, event, topic) and differentiates from siblings 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?

Explicitly describes when to use each mode (no args for trending scan, event for per-event, topic for cross-event) and when not to trade (realizable_edge_pp <= 0). Missing explicit comparison with sibling tools, but provides strong guidance.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description goes far beyond, explaining the three model families, edge calculation, Kelly sizing, liquidity and spread handling, diagnostics, and caching behavior. 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 lengthy but well-structured with section headers. Every sentence provides useful information, but it could be more concise for an AI agent. It front-loads the purpose but the density may be overwhelming.

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

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

Given the complexity and no output schema, the description fully explains the return structure (by_segment, diagnostics), edge calculation, caching, and special notes like Fed bets. It is comprehensive and leaves no major gaps.

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

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

All 9 parameters are described in the input schema (100% coverage). The tool description adds value by grouping them as tradeable-edge knobs and explaining their interaction (e.g., min_kelly skipping small opportunities). This enhances understanding beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It specifies the resource (Polymarket markets) and action (scan and return opportunities), distinguishing it from siblings like polymarket_arbitrage. The purpose is explicit and actionable.

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

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

The description explains when to use the tool ('what should I bet on today') and details the tradeable-edge knobs for filtering. However, it lacks explicit guidance on when not to use this tool versus alternatives like polymarket_arbitrage, leaving some ambiguity about choice.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds significant behavioral details: history bounded by 60-day TTL, snapshot availability from when enabled, and that decay is computed from daily closes of edge_pp_net (not intraday). 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 paragraph that is well-structured and front-loaded with the core purpose. It efficiently covers the primary question, explains the response structure (tracked, expired, snapshot_dates), and includes limitations—all without unnecessary verbosity. Every sentence adds value.

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

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

Despite lacking an output schema, the description thoroughly explains the response fields (tracked with edge_pp_net time-series, trend, decay_pp_per_day; expired with lifespan_days; snapshot_dates). It also covers limitations like snapshot TTL and computation details, making the tool's behavior fully comprehensible for an AI agent.

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

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

Schema coverage is 100% with clear descriptions for both parameters (days lookback, window snapshot family). The description restates these with defaults and limits (max 30 for days, default '1wk' for window) but adds no new semantic meaning beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It explicitly answers the question 'how long has this edge existed and is it shrinking?', and distinguishes itself from the sibling tool 'polymarket_edges' by focusing on time-series history rather than current edges.

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

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

The description gives strong usage context by explaining the difference between a fresh wide edge and an old one, implying when to use this tool for decay analysis. It does not explicitly compare with alternatives like 'polymarket_edges', but the purpose is clear enough. The detailed output structure helps further guide appropriate use.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) indicate safe read-only operation, and the description adds rich behavioral detail: walks the ladder, returns specific fields (top_of_book, slippage, fill details, verdict), warns about thin_legs and forced_directional_risk. 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?

Description is thorough and well-structured with bold headings, all-caps key terms, and clear mode separation. Every sentence adds value. Slightly verbose but appropriate for the complexity.

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

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

Despite no output schema, description fully covers both modes' return fields, explains verdict values, edge cases (thin legs, forced directional risk), and how to interpret results. Highly complete for safe and effective tool usage.

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?

All 4 parameters have schema descriptions (100% coverage). Description adds meaning by explaining modes (single-market vs basket), parameter interactions (side default auto for basket), and interpretation of size_usd per mode. Enriches schema 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?

Description clearly states it's a realizable-vs-theoretical edge check against live CLOB order-book depth, with two distinct modes (single-market and basket). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly directing usage before those tools for certain conditions.

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: before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. Explains rationale (theoretical overround not capturable, partial fills cause directional risk). Prerequisites (one of market or event) are clear. Does not cover all non-use cases but provides strong 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 extensively discloses behavioral traits beyond annotations: compatibility_warning conditions, temporal_alignment, skipped_cross counters. Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false, and description adds critical context about when spreads are meaningful or not.

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

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

The description is thorough but somewhat verbose, with repeated warnings ('pre-mapped ≠ tradeable'). It is well-structured with sections but could be more concise. Every sentence earns its place, but overall density is high.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly explains return values (leg-by-leg prices, spread, safety fields) and how to interpret edge cases. It is complete for the task.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds context about mode behavior and overrides but does not add meaning beyond what the schema provides. 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 it is a cross-venue spread tool comparing Kalshi and Polymarket prices for the same resolving question. It uses specific verbs ('cross-venue spread') and distinguishes itself from sibling tools (none appear to do cross-venue analysis).

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

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

Provides clear when-to-use guidance via two modes (topic shortcut or explicit ticker) and explains context for interpreting spreads. However, it does not explicitly state when NOT to use or mention alternatives (e.g., single-venue tools).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as false. The description adds context about scoping and listing behavior but does not significantly extend behavioral disclosure beyond the annotations.

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

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

The description is concise, front-loaded with the core action, and every sentence adds value. No unnecessary words.

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

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

Given the simple tool (one optional parameter, no output schema), the description covers purpose, usage, scoping, and pairing with siblings. It is complete for the tool's complexity.

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

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

Schema coverage is 100% with the key parameter described. The description adds context about what keys might represent (ticker, address) but does not add new semantic information beyond the schema.

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

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

The description clearly states the tool retrieves a value previously saved via remember or lists all saved keys when the key argument is omitted. It distinguishes from sibling tools like remember and forget.

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

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

The description provides explicit use cases (looking up stored context like ticker, address, notes) and advises pairing with remember and forget. It does not explicitly state when not to use it, but the guidance is clear.

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

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

Discloses side effect of mark_read parameter (flagging events read) and notes polling is fine. Mentions the feed URL alternative. However, there is a contradiction with the readOnlyHint annotation (true) since mark_read modifies state.

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 core purpose, then structured details. Every sentence adds value: purpose, returned fields, filter options, side effect, and alternative access method.

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 5 optional parameters and no output schema, the description explains return fields, filter options, side effect, and provides an alternative access method, making it complete for effective use.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds examples (e.g., 'sec_8k' for type) and clarifies behavior (mark_read flagging, since as ISO timestamp), providing extra meaning beyond the schema.

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

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

The description clearly states it pulls fired events from subscription feed, returns recent alerts with specific fields (source, citation_uri, raw payload), and filters by type/since. It distinguishes from sibling subscription management tools by focusing on retrieval of alert 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?

The description implies polling is acceptable and points to an alternative HTTP endpoint for scripts/dashboards, providing context for when to use this tool vs direct access. However, it does not explicitly state when not to use it or compare to sibling retrieval tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: fans out to multiple APIs (SEC, GDELT→GNews, USPTO), fallback logic, soft-fail for USPTO, and return structure (changes grouped by source, total_changes count, citation URIs). No contradictions.

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

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

The description is a single dense paragraph that front-loads with example queries. Every sentence provides useful information, but the density could be improved with bullet points or clearer structure for the multiple sources.

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 has three required parameters, no output schema, and moderate complexity (multiple sources, fallbacks, return format), the description covers return types, citation URIs, and limitations (USPTO soft-fail). It also provides sibling differentiation. Missing explicit mention of error handling or timeouts, but otherwise complete.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds semantic value by clarifying the 'since' parameter accepts ISO date or relative shorthand, recommends typical values, and explains that 'value' can be ticker or CIK. The 'type' parameter is correctly limited to 'company'.

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

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

The description clearly states the tool produces a 'change feed for a company in the last N days/weeks/months' across multiple sources, and it explicitly distinguishes itself from the sibling 'entity_profile' by advising when to use that alternative. Example queries further clarify the use case.

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 example user intents, guidance on the 'since' parameter (e.g., 'Use "30d" or "1m" for typical monitoring'), and notes fallback behavior for news sources. However, it does not explicitly state when not to use this tool, or contrast with other siblings beyond entity_profile.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds behavioral details: key-value scoping, persistence differences for authenticated vs anonymous users (24-hour retention). 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 three sentences, front-loading the core purpose. Every sentence adds value (purpose, usage guidance, behavioral details). No wasted words.

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

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

For a simple tool (2 required params, no output schema), the description covers all necessary aspects: purpose, usage, behavior, and relationships to sibling tools. No gaps remain.

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

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

Schema coverage is 100% with descriptions for key and value. The description adds example keys and value description but does not significantly expand beyond the schema. Baseline 3 is appropriate as schema already handles parameter semantics.

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

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

The description clearly states the tool's verb ('Save data') and resource ('data the agent will need to reuse later'). It distinguishes itself from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete.' This provides unique purpose and 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 gives explicit guidance on when to use ('when you discover something worth carrying forward') and provides concrete examples. It also directs to alternatives: 'Pair with recall to retrieve later, forget to delete.' This covers both usage context and 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?

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description adds valuable behavioral details: identifiers are source-labelled, unresolved identifiers are explicitly listed under `unresolved`, and external enrichment degrades gracefully. These traits are not obvious from annotations alone.

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

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

The description is lengthy but well-organized with 'SUPPORTED TYPES' and explicit sub-bullets. Every sentence adds value, though the opening list of example queries is somewhat redundant. The structure makes scanning easy and is front-loaded with the core purpose.

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

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

Given there is no output schema, the description thoroughly covers expected outputs (CIK, LEI, FIGI, RxCUI), source attribution, unresolved handling, and fallback behavior. It provides enough detail for an agent to confidently invoke the tool and understand what to expect from the response.

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, but the description adds meaning by explaining what each type returns and providing concrete input examples (e.g., ticker AAPL, CIK 0000320193, drug names). It also clarifies that company type accepts multiple input formats, going beyond the schema's terse descriptions.

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

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

The description clearly states the tool resolves names to canonical/official identifiers and provides multiple example queries to illustrate intent. It distinguishes the tool from siblings by explicitly saying 'Use FIRST whenever you have a name but need an ID' and listing supported entity types.

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

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

The description provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and gives concrete example queries. It does not explicitly name alternative tools or state when not to use it, but the 'use first' directive is a strong contextual signal.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by revealing the internal mechanism of probing with ai_visibility_check and specifying the output format (ranked list with score, confidence, signal density). 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 concise at three sentences, each serving a purpose: stating the main action, explaining the process, and providing a use case. No unnecessary words.

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

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

The description explains the return format and use case, compensating for the lack of output schema. It covers behavior, input semantics, and output shape. It does not address error handling or rate limits, but is sufficient for a read-only comparison 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 adds minor context by explaining that the first entity is treated as the 'subject' and the rest as competitors, but does not significantly enhance understanding beyond the schema.

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

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

The description uses specific verbs like 'compare', 'probes', 'ranks', and 'surfaces' to clearly state the tool's purpose: comparing AI visibility across multiple entities. It distinguishes itself from sibling tool 'ai_visibility_check' by focusing on multi-entity comparison.

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

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

The description provides a concrete use case for competitive AI-marketing audits and explains that it probes each entity with ai_visibility_check. It implicitly suggests usage over the single-entity tool, but does not explicitly state when not to use it or mention 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds critical behavioral details: bundlephobia first measurement can take 5-30s, sources_failed lists timeouts, partial failures degrade gracefully. 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?

Single dense paragraph front-loaded with purpose, then usage, then return format, then limitations. Every sentence adds value; no fluff or repetition.

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?

Complex tool with no output schema, but description lists all returned fields (summary block, per-advisory, links, alternative versions) and explains partial failure behavior. Schema coverage 100% on parameters. Complete enough for an agent to understand inputs and outputs.

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% (both parameters documented). Description repeats that version defaults to latest and scoped packages accepted, adding no new meaning beyond schema. 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?

Description uses specific verb ('scan') and resource ('dependency'), clearly states it's a composite check for npm packages combining deps.dev and bundlephobia. Distinguishes from siblings by scoping to NPM ecosystem only, with explicit mention that other ecosystems use deps.dev directly.

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?

States when to use: agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Scopes to NPM only, mentions partial failure behavior. Does not explicitly exclude alternatives but provides clear context.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by noting the tool is keyless, searches an open community database, and optionally restricts by organism. No contradictions.

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

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

The description is very concise: four short sentences that front-load the purpose and provide essential details without wasted words. Every sentence adds value.

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

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

For a search tool with 3 parameters and no output schema, the description covers the main points: purpose, database, examples, optional filter, and external context. It could briefly mention expected return format, but overall sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats parameter info (e.g., organism can be Latin or common name) but adds no new semantics beyond what the schema provides.

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

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

The description clearly states the tool searches WikiPathways for biological pathways by name, with examples like glycolysis and apoptosis. It distinguishes itself from siblings (e.g., get_pathway, list_pathways) implicitly, and mentions complementing KEGG/Reactome.

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 some context (keyless, complements other databases) but does not explicitly state when to use this tool versus sibling tools like get_pathway or list_pathways. Usage guidance is implied but not direct.

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

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

Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description adds significant detail: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char overlapping windows, and caps input at 200K chars with truncation flag. 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?

Three sentences, front-loaded with the core function, and every sentence adds unique value. No redundant or extraneous information.

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

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

Given the tool has 3 parameters, no output schema, and annotations that are well-supplemented, the description explains how the search works (embeddings, windowing), constraints (character cap), output details (offsets, scores), and usage guidance. It is fully self-contained.

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

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

Schema coverage is 100%, but the description adds value by explaining the truncation behavior for long inputs, providing example queries, and detailing the output format (passages with offsets and scores). This goes beyond the schema's minimal descriptions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and explains the specific use case of searching within large text. It distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and noting it is for when the record is too big for the prompt.

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 guides usage: 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. It also provides example queries and notes that every passage carries an offset for verification.

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?

Adds many behavioral details beyond annotations: requires OAuth, returns subscription id, lists supported types with examples, describes delivery channels with constraints (SMS cap, webhook auto-disable). 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?

Well-structured and front-loaded with purpose; every sentence adds value. While lengthy, it's necessary detail for a complex tool with nested parameters.

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?

Fully complete description for a complex tool with 100% schema coverage. No output schema needed as return value is specified. Covers all required 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?

Adds significant meaning beyond the schema: explains each enumeration value with examples, provides detailed param format per type, and elaborates on delivery channel options and validations.

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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. Differentiates from sibling tools like unsubscribe and list_subscriptions.

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

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

Provides context on account requirements (Pipeworx OAuth) and mentions alternative tools like recent_alerts for feed pull. However, no explicit when-to-use vs when-not instructions.

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 further explains behavior: returns category-bucketed examples drawn from a live catalog, and the effect of omitting or providing the 'topic' parameter. No contradictions with annotations.

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

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

The description is a single paragraph that efficiently packs purpose, categories, and usage instructions. It is front-loaded with the core purpose. However, it could be slightly more structured (e.g., bullet points for categories) to improve scanability, but it remains clear and concise for the amount of information.

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

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

Given the tool's simplicity (one optional param, no output schema), the description provides complete context: explains what is returned (category-bucketed examples with tool + argument shapes), how to call it, and when to use it. No gaps remain for effective agent selection and invocation.

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

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

Schema coverage is 100% (one parameter with description). The description adds further meaning: it lists possible topic values (finance, pharma, etc.), explains that omitting gives a full spread, and clarifies the purpose of focusing the output. This goes beyond the schema's minimal description.

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

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

The description clearly states the tool's purpose: it serves as an onboarding entry point, returning category-bucketed example questions with exact tool + argument shapes. It distinguishes itself from siblings like ask_pipeworx, entity_profile, etc., by focusing on showcasing what the agent can do and how to call meta-tools.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also mentions alternative tools (ask_pipeworx, entity_profile, compare_entities) and explains how to customize the call with the 'topic' parameter.

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

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

Annotations indicate mutation and nondestructive behavior. Description adds crucial context: row is deactivated not deleted, historical events remain via recent_alerts, and ownership is enforced. Goes beyond annotations significantly.

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

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

Two sentences, front-loaded with purpose, each sentence provides essential information without 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 tool with one parameter and good annotations, the description covers purpose, ownership, side effects, and linkage to related tool (recent_alerts). No gaps.

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

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

Schema coverage is 100% with a clear description of 'id' as uuid from subscribe. Description doesn't add extra parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

Description clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from sibling tools like subscribe and list_subscriptions by mentioning ownership enforcement and deactivation behavior.

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

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

Description explicitly states ownership enforcement, guiding use to own subscriptions only. Implicitly suggests having a subscription id from subscribe. No explicit when-not-to-use or alternatives, but clear enough for typical use.

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

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

Beyond the annotations, the description discloses key behaviors: it returns a verdict (confirmed, approximate, refuted, etc.), provides a grounded or structured value with citation and reasoning, and explains special meanings for could_not_verify vs. unsupported. It also describes routing logic and error details, which significantly enriches the agent's understanding of what the tool does internally.

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, starting with natural-language triggers and moving to usage guidance, routing logic, return values, and important edge cases. Every sentence adds meaningful information, and the structure is logical for a tool with this level of complexity. No filler or redundancy.

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

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

The description covers all essential aspects: the purpose, target claims, routing between two pipelines, verdict types, citation format, reasoning, and the precise meaning of edge-case results (could_not_verify vs. unsupported). Given the tool's complexity and the lack of an output schema, the description fully compensates and leaves no critical gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how tolerance_pct works in relation to claim wording (default capped at 5) and how it affects verdict grading, which is not fully evident from the schema alone. It also gives concrete claim examples that illustrate the expected input format.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It includes specific trigger phrases ("Is it true that…") and distinguishes between company-financial claims (SEC EDGAR fast path) and other claims (grounded pipeline), making the tool's scope unambiguous and setting it apart from sibling tools like deep_research or ask_pipeworx_grounded.

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

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

The description explicitly tells callers when to use the tool: "Use whenever the agent needs to check whether something a user said is factually correct." It also differentiates between the structured path for company-financial claims and the grounded path for any other claim, and notes it replaces 4–6 sequential calls, giving clear context on when it is the right choice.

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