Opencollective

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral detail: default model (Workers AI Llama-3.3-70b), that _apiKey enables Anthropic probes (BYO key, user pays Anthropic), and the return format per model. 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 extremely concise: two sentences that front-load the core purpose and then efficiently cover key details (default, BYO key, return format). Every sentence contributes meaningful information 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?

No output schema exists, yet the description specifies return fields (score, confidence, signals, raw_response) per model plus a combined view. It also covers the default model and optional parameters. It lacks details on error handling or rate limits, but given the low complexity (4 params, read-only), it is sufficiently complete.

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

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

Schema coverage is 100% (all parameters described in schema). The description adds meaning beyond the schema: explains default model behavior, clarifies when _apiKey is needed, and highlights context's disambiguation purpose. This adds value for the agent.

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', 'business/brand/product/topic'). It distinguishes from sibling tools like 'ask_pipeworx' by focusing on multi-model visibility scoring rather than querying a single assistant.

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 outlines specific use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains optional parameters (models, _apiKey, context). However, it does not explicitly state when not to use this tool or compare it to alternatives like 'entity_profile' or 'scan_competitor_ai_presence'.

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. Description adds that it routes to 5,008 tools across 1,318 sources and returns structured answers with stable citation URIs, providing rich behavioral context.

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

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

Front-loaded with key guidance ('PREFER OVER WEB SEARCH'), but the list of source types is somewhat lengthy. However, every sentence serves a purpose, and the structure is logical.

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 this complexity (many sources, many siblings), the description is remarkably complete: it covers purpose, usage, alternatives, parameter, return format, and even account tier implications.

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 single 'question' parameter (plus aliases). Description explains the parameter, provides multiple examples, and clarifies that any alias works, adding value beyond the schema.

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

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

Clearly states the tool routes questions to a large set of sources and returns structured answers with citations. Distinguishes from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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 preferring this over web search for factual questions, provides specific examples, and clearly states when to step up to other tools (ask_pipeworx_grounded for high-confidence, deep_research for broad questions).

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds specific behavioral context: source-preference ranking and its live nature. It also clarifies it is a full working router, not a fallback.

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 long, front-loads the purpose and key difference, and contains no redundant 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 complexity of a router to 5k tools, the description explains the experimental nature, source preference, and that results are compared to stable. No output schema exists, but phrasing 'same response shape' references sibling knowledge, which is acceptable.

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 six parameters are documented in the schema with descriptions for aliases, so the description adds no further parameter-level meaning, meeting the baseline 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 it is a 'universal router' with '5,008 tools' and highlights the experimental feature of 'source-preference ranking', distinguishing it from the stable 'ask_pipeworx' sibling.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts with the stable router for comparison, providing clear context for when to use this beta version.

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?

Describes key behavioral traits: extracts answer only from tool result, returns explicit refusal with reasons, costs extra LLM call. Annotations already declare readOnlyHint and idempotentHint, but the description adds critical context about the refusal mechanism and data source handling.

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

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

The description is well-structured with front-loaded key concepts. It is relatively long but every sentence adds value. Could be slightly more concise, but overall efficient.

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

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

Given the tool's complexity (6 parameters, no output schema), the description fully covers purpose, usage, behavior, return fields, and refusal reasons. The annotations provide safety hints, and the description complements them well.

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

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

The input schema covers all 6 parameters with aliases and descriptions. The description only mentions 'Your question in natural language,' which adds no meaning beyond the schema. With 100% schema coverage, a 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 it is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes itself from ask_pipeworx by specifying the extra extraction step and explicit refusals. The verb 'extracts' and resource 'tool result' are specific and unique.

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 provides when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when to prefer the sibling ask_pipeworx ('casual lookups'), including cost trade-off. This is clear 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 (readOnlyHint, idempotentHint) are complemented by rich behavioral details: resolution contract, parent event extraction, news fallback, safety short-circuits, closed market handling, wide-spread warnings, and cancellation rule parsing. 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 well-structured with labeled sections but is quite lengthy. It is front-loaded with the core purpose but could be more concise, though every sentence adds important detail.

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

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

Despite no output schema, the description comprehensively covers response shapes (market, analysis, evidence, resolver contract, parent_event, news fields) and edge cases (low-confidence, closed markets, wide spreads, cancellation rules).

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 3 parameters. The description adds valuable examples (market_input) and explains enum options (depth: quick/thorough) and the include_raw flag's effect on response size.

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 researches Polymarket bets by pulling Pipeworx data, and lists inputs (slug, URL, question) and outputs (evidence packet, comparison). This clearly distinguishes it from sibling tools like polymarket_edges or validate_claim.

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

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

The description provides clear use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and fan-out examples but does not explicitly state when to avoid using it or name alternatives.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds context by stating it returns 'public' info, which clarifies access scope. 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, well-structured sentence of 8 words with no unnecessary information. It is front-loaded with the core action and resource, making it immediately scannable.

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

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

Given the tool's simplicity (one parameter, output schema present), the description is mostly complete. It lacks details like case sensitivity of slug or behavior on missing slug, but these are likely covered by the schema and error handling. Annotations and output schema fill most 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?

Input schema has 100% description coverage on the single parameter 'slug' with examples. The description simply says 'by slug', which is already implied by the schema. No additional semantic value added 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 action (get info), the resource (collective by slug), and the specific fields returned (name, balance, currency, sponsors). It distinguishes itself from sibling tools like 'entity_profile' by being specific to collectives and using a slug identifier.

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 when you have a slug and need public collective info, but it provides no explicit guidance on when to use this tool versus alternatives (e.g., 'entity_profile') or when not to use it. This leaves some ambiguity for the agent.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds value by detailing data sources (SEC EDGAR/XBRL, FAERS), handling of fiscal years, and output format (paired data + citation URIs). This provides useful 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 a single dense paragraph that is front-loaded with trigger phrases and provides all key information. It's efficient but could benefit from slightly more structure (e.g., separating triggers from behavior) without losing 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?

Given no output schema, the description covers return format ('paired data + pipeworx:// citation URIs'), sorting, data sources, and performance benefit. It adequately addresses the complexity of a comparison tool with two entity types.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the entity type enum with data sources, and for 'values' it gives concrete examples (tickers/CIKs for company, drug names), min/max constraints, and how results are sorted. This goes well 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 compares 2-5 companies or drugs in a single parallel call, using trigger phrases like 'X vs Y' and specifying data sources for each type. It distinguishes itself from sequential single-pack lookups, making its purpose unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool vs alternatives. However, it doesn't explicitly list when not to use it, though the context is sufficient.

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

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

Discloses numerous behaviors beyond annotations: account requirement, paid plan, not open-web search, parallel decomposition, returns findings with fields, gaps array, contradictions for standard/thorough, semantic excerpting, and expected timing. 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?

Very verbose (300+ words) with many specific numbers and details that may not be necessary for agent decision-making. Could be more concise while retaining key guidance. However, it is front-loaded with critical prerequisites and alternatives.

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 complexity and no output schema, the description covers prerequisites, behavior, return format (findings, gaps, contradictions, hop, citation), timing, and edge cases (breaking news). An agent has sufficient context to invoke correctly.

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

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

While schema already covers both parameters, the description adds deep semantics: explains depth enum values with exact numbers, behavior changes (gap-recovery, contradictions), and that question can be broad/multi-part. Schema coverage is 100%, but description still adds significant value.

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

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

The description clearly defines the tool as a multi-source structured research engine across Pipeworx's data sources, contrasting it with sibling ask_pipeworx for single lookups and breaking news. It specifies the exact use case of broad/multi-part questions over structured data.

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

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

Explicitly states when to use this tool vs ask_pipeworx: not signed in, single lookup, breaking news. It also notes account requirements and paid plan for 'thorough' depth.

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. Description adds that it returns top-N relevant tools with schemas and examples, and results are ready to call directly, which adds useful 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?

Description is well-structured: first sentence states purpose, then lists domains, then details return value, then usage tip. Every sentence adds value with no fluff.

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

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

Given the tool's simplicity, good schema coverage, and annotations, the description fully covers purpose, usage, and return format. No output schema needed.

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

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

Schema description coverage is 100% with all 6 parameters documented. Description adds value by providing example queries and mentioning aliases, going 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 finds tools based on data/task descriptions, with a specific verb 'find' and resource 'tools'. It distinguishes from siblings by being a meta-tool, listing numerous example domains.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for' and 'Call this FIRST when you have many tools available and want to see the option set'. Provides clear context and an alternative (not just one answer).

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 comprehensive behavior: fans across multiple sources, returns specific fields, mentions USPTO patent sunset and soft-fail, and names not supported. Adds context beyond annotations (readOnlyHint, etc.) with details on data sources and error handling. No contradiction with annotations.

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

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

The description is front-loaded with examples and structured logically. While slightly wordy, every sentence adds necessary information. Could be slightly more concise but remains effective and easy to parse.

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

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

Given the tool's complexity (multiple sources, no output schema), the description is comprehensive. It explains all return fields (filings with URIs, fundamentals sorted, patents, news, LEI) and limitations. Complements sibling tools by being the holistic option.

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

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

Schema coverage is 100% with both parameters described. The description adds value by clarifying that 'type' is only 'company' and 'value' is ticker or CIK, explicitly stating names not supported. This goes beyond the schema's enum and string descriptions.

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

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

The description clearly states the tool's purpose: providing a full cross-source profile of US public companies. It lists example user queries and specifies the returned data (CIK, filings, fundamentals, etc.). It distinguishes itself from siblings by recommending preference over chaining single-pack lookups for holistic views.

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 on when to use (holistic view, prefer over chaining) and when not (names not supported, need resolve_entity). Includes behavioral notes like USPTO sunset soft-fail. Provides clear alternatives and constraints.

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 no information beyond these annotations, missing opportunities to explain behavioral traits like external data dependency or result variability.

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 short but not concise in a helpful way. It lacks essential information, making it under-specified rather than efficient.

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

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

Given the output schema exists, the description need not detail returns, but it still leaves ambiguity about what events are retrieved and how the 'slug' parameter determines results. The complete picture is missing.

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

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

The single parameter 'slug' has no description in the schema (0% coverage) and the tool description does not explain its meaning or format. The description adds no value beyond the schema.

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

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

The description 'Events for a collective' is vague and does not specify what action the tool performs (e.g., list, get, search). It fails to distinguish from sibling tools like 'collective' or 'members'.

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?

No guidance on when to use this tool vs alternatives. The description provides no context for appropriate usage scenarios 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 show destructiveHint=true and idempotentHint=true, so description's 'Delete' is consistent. Adds context about clearing sensitive data but doesn't detail error behavior or side effects. No contradiction.

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

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

Two sentences: first states purpose, second gives usage guidance. No wasted words, front-loaded effectively.

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

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

With one parameter fully described in schema, annotations present, and no output schema, the description provides enough context 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 coverage is 100%, and the description does not add meaning beyond the schema's 'key' parameter description. Baseline score applies.

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

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

Description explicitly states 'Delete a previously stored memory by key.' Verb 'Delete' and resource 'memory' are clear. Distinguishes from siblings like '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?

Provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' Also recommends pairing with 'remember' and 'recall' as alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context: 'Fetches the page, extracts title/description/key links, and emits standard llms.txt format.' This explains the internal behavior and output format beyond what annotations provide.

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

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

The description is highly concise: three sentences that front-load the purpose, process, and use cases. Every sentence earns its place with no redundancy or filler.

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

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

Despite no output schema, the description explains the output format (standard llms.txt markdown, single text blob) and use cases. It is sufficient for an agent to understand what the tool produces and when to invoke it. Minor gap: no mention of error handling or limitations.

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. The description adds no additional parameter-specific details beyond the schema. Baseline of 3 is appropriate as the schema already does the heavy lifting, and the description does not significantly enhance parameter understanding.

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

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

The description clearly defines the tool's purpose: generating an llms.txt file for a given URL. It specifies the verb 'generate', the resource 'llms.txt file', and the context of AI crawlers. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on a specific output format and use cases.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor. However, it does not specify when NOT to use it or mention alternatives among sibling tools, leaving a minor gap in 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, idempotentHint, destructiveHint, and openWorldHint. Description adds return fields and active default, but adds limited 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?

Two sentences, front-loaded with purpose and return fields, then usage guidance. No wasted words.

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

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

Given a simple tool with one optional parameter and no output schema, the description adequately explains what it does and returns. Minor improvement could include pagination if any, but not necessary.

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 parameter description in schema is clear, and the description adds context that defaults to active only, enhancing meaning slightly.

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 lists active subscriptions and specifies the return fields. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing existing 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?

Explicitly advises when to use: to review monitoring before adding more or to find an id to cancel, providing clear context for invocation.

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, destructiveHint=false, and idempotentHint=true, so the agent knows this is a safe, read-only operation. The description adds that the tool returns member roles for a collective, which provides some 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?

Single sentence with no waste. It is front-loaded with key information. Could be slightly more verbose to include parameter hints, but remains concise.

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?

Output schema exists, so return value explanation is not needed. However, the description omits the meaning of the required 'slug' parameter and does not explain how to specify a collective. This is a gap for a tool with only two parameters.

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 50% (role has description, slug does not). The description lists role types (backers/sponsors/admins/contributors) but does not clarify the 'slug' parameter meaning. Baseline 3 since coverage is not low, but the description does not compensate for the missing slug 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 specifies the resource (members) and types (backers/sponsors/admins/contributors) for a collective. It is clear but could be improved by adding an explicit verb like 'list' or 'get'. It distinguishes from sibling tools as no other tool targets members.

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?

No guidance on when to use this tool versus alternatives. The description does not mention prerequisites or context for usage.

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

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

Beyond annotations, description reveals rate limit (5 per identifier per day), free usage, and no quota impact. Annotations show readOnlyHint=false, destructiveHint=false, and description adds non-obvious behavioral details.

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?

Concise, three-sentence description that front-loads the purpose. Every sentence adds essential information without redundancy.

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

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

Given the tool's simplicity and lack of output schema, the description covers all necessary aspects: use cases, content guidelines, rate limits, and quota impact. No gaps identified.

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

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

Schema covers all parameters with descriptions. The description adds value by specifying how to write the 'message' parameter (be specific, 1-2 sentences) and reinforcing the enum categories. This goes beyond schema documentation.

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

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

Clearly states the tool's purpose: sending feedback to Pipeworx. Distinguishes from sibling tools by specifying use cases (bug, feature, data_gap, praise). No other sibling tool focuses on feedback.

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 (bugs, missing features, praise) and what to avoid (pasting end-user prompts). Provides context on rate limits and quota implications.

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, and destructiveHint=false, indicating a safe, non-destructive operation. The description adds valuable context: self-aggregating, no PII, cache durations (5min-1h), and derivation from CF analytics-engine, which enhances transparency 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 multiple sentences but each adds distinct value: core function, use cases, data source, caching, and parameter guidance. It is front-loaded with the primary result, making it efficient. Minor redundancy could be trimmed, but overall it's 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 low complexity (1 optional param, no required fields, no output schema), the description covers all necessary aspects: what is returned, why it's useful, data origin, privacy, and caching. It fully equips an agent to use the tool correctly without needing additional context.

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

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

Schema coverage is 100% for the single optional parameter 'window'. The description adds semantic meaning by explaining the trade-off between shorter windows (what's hot) and longer windows (steady-state demand), which helps the agent choose appropriately without overburdening with syntax details.

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

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

The description clearly states the verb ('returns') and the resources ('top tools, top packs, and total call volume') with explicit scope ('over a recent window'). The purpose is distinct from sibling tools such as 'ask_pipeworx' or 'discover_tools' which serve different functions.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming a popular tool, seeing alignment) which help the agent decide when to invoke this tool. It does not explicitly state when not to use it or list alternatives, but the guidance is strong enough to differentiate usage.

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

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

Describes extensive behavioral details: scans top 200 markets, walks child markets, checks ordering, partition checks, placeholders filtering, fill check against live depth, and trade recommendations. Adds context beyond annotations (which already declare read-only and idempotent). No contradiction.

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

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

Well-structured with sections, bullet points, and clear mode separation. However, it is relatively long and could be slightly more concise without losing critical details. Justified by complexity but just short of excellence.

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

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

Given no output schema, the description fully covers return values: opportunities with gap_pp, suggested_trade, reasoning, monotonicity context, and partition check fields. Also explains internal filters and fill check logic. Complete for a complex analytical 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?

Adds substantial meaning beyond input schema: explains each parameter's mode, provides example values, describes internal logic like semantic anchor (Jaccard similarity), partition filter, and fill check. Schema already has descriptions but description enriches them significantly.

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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between no-arg trending scan, event mode, and topic mode, each with concrete examples. No confusion with sibling tools.

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

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

Provides explicit when-to-use guidance: call with NO args for trending scan, pass 'event' for per-event partition check, 'topic' for cross-event scan. Recommends event mode for specific markets and notes to use polymarket_fill_risk for custom sizing. Clear exclusions and alternatives.

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

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

The description discloses extensive behavioral traits: caching at 1h KV level keyed on all knobs, return of diagnostics for empty segments, tradeable-edge filters, model family characteristics (soft signals, rare-by-design), and Fed note. Annotations (readOnly, idempotent, openWorld) are consistent and the description adds significant context.

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

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

The description is overly long, containing detailed model family explanations and technical specifics that could be condensed or moved. The structure front-loads the purpose but then expands into verbose details, making it less concise than ideal.

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 (9 parameters, multiple model segments, caching, diagnostics), the description fully covers what the tool returns (by_segment, fed_candidates, _diagnostics) and explains the behavior of each segment. Without an output schema, this level of detail is necessary and provided.

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 detailed descriptions for each parameter. The main tool description does not add per-parameter meaning beyond what is in the schema, but the schema already provides sufficient context. 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 that the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, explicitly built for the 'what should I bet on today' use case. It distinguishes itself from siblings by focusing on model-driven 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 implies usage for discovering betting opportunities and mentions Fed bets are excluded from ranking. However, it does not explicitly compare to sibling tools like bet_research or polymarket_arbitrage, nor does it provide clear 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=true, idempotentHint=true, destructiveHint=false, so the agent knows it's safe. The description adds behavioral details: the tool computes trends and decay rates from daily closes, explains snapshot gaps, and clarifies that decay numbers are daily closes not intraday. This adds value 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 long but front-loaded with the core purpose. It lists response fields in a structured way. Some verbosity in the response details, but it's necessary for clarity. Every sentence adds value, though it could be slightly more concise.

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

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

No output schema exists, so the description fully covers return values: tracked[], expired[], snapshot_dates[] with field details. It also mentions limits and caveats (TTL, snapshot gaps). For a tool with two optional parameters and a detailed response, this is very 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 both parameters. The description adds default values (days=14, window='1wk') and range (days max 30, clamp 2-30). This is helpful but not extensive; baseline 3 is appropriate since schema already carries the main burden.

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

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

The description states a specific purpose: edge persistence and decay telemetry from daily snapshots. It uses specific verbs and resources ('answers how long has this edge existed and is it shrinking?') and implicitly distinguishes from the raw edges tool (polymarket_edges sibling) by adding time-series analysis.

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

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

The description explains the use case: comparing fresh vs. aged edges. It mentions that a 3-week-old wide edge is different from a fresh one, providing context. While it doesn't explicitly say when not to use, the limits section (60-day TTL, snapshot gaps) gives practical guidance. Clear context but no explicit 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?

Adds significant context beyond annotations: requires one of market/event, walks the ladder, returns verdict, warns about forced directional risk and thin books. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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 with clear sections (SINGLE-MARKET, BASKET) and bold key terms. Slightly verbose but every sentence adds value; minor redundancy in mode descriptions.

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

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

Comprehensive for a complex tool with two modes, no output schema. Covers return fields, edge cases (thin legs, forced directional risk), and usage context thoroughly.

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 meaning beyond schema: clarifies size_usd interpretation (max spend on buys, target proceeds on sells), default side in basket mode, and that one of market/event is required (despite schema not marking them required). 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 clearly states the tool checks 'realizable-vs-theoretical edge against live CLOB order-book depth', differentiates between single-market and basket modes, and lists specific return fields. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why (theoretical overround not capturable, partial basket fills lead to directional risk), providing excellent guidance.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), description details response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and common pitfalls. 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?

Description is detailed but well-structured with sections (modes, response, safety). Uses bold for key terms. Every sentence adds information; could be slightly trimmed but remains efficient.

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

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

Given complexity (3 parameters, no output schema), description fully covers tool behavior, response fields, warnings, and edge cases. Provides complete contextual understanding for an AI 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?

All three parameters (topic, kalshi_event_ticker, polymarket_event_slug) are documented in schema. Description adds value by explaining that topic is a pre-mapped shortcut and the explicit parameters override it. With 100% schema coverage, description adds meaningful context above baseline.

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

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

Description clearly states the tool computes cross-venue spread between Kalshi and Polymarket. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison. Specific verb 'spread' and resource 'cross-venue' make 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?

Explains two modes (topic and explicit) with examples and warns that pre-mapped topics often not tradeable. Provides context on when to use, but lacks explicit 'when not to use' compared to alternatives like direct event lookups.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: the tool is scoped to an identifier and can list all keys when key is omitted, which goes beyond annotation information.

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

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

The description is very concise with three sentences, no fluff, front-loaded with the primary purpose, and each sentence adds necessary information. It efficiently conveys the tool's function and usage.

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 low complexity (1 optional parameter, no output schema) and good annotations, the description fully covers the tool's behavior, usage context, and relationship to sibling tools, making it complete for an agent to use correctly.

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

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

Schema coverage is 100% with description for the 'key' parameter. The tool description adds meaning by explaining the dual behavior of retrieving a specific value or listing all keys, and mentioning scoping, which enriches the parameter's semantics 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 values saved via 'remember' or lists all keys when no key argument is given. It distinguishes itself from sibling tools like 'remember' and 'forget' by specifying this exact behavior.

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

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

The description explains when to use the tool: to look up previously stored context like user target ticker or research notes. It provides scoping context and pairs with 'remember' and 'forget', but does not explicitly contrast with searching alternatives like 'search_within' or 'deep_research'.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds useful context about the return fields, the side effect of mark_read, and polling suitability. This goes beyond the annotations, so a 4 is warranted.

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, with three front-loaded sentences that each add value. No wasted words, and the purpose is immediately 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?

Given the tool's complexity (5 optional parameters, no output schema, but comprehensive annotations), the description covers the essential behavioral aspects, return data, parameter usage, and polling feedback. It is fully adequate for an AI agent to understand and invoke the tool correctly.

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

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

The input schema has 100% coverage with descriptions for each parameter. The description mentions filtering by type and since, and explains mark_read's behavior, but adds only marginal value beyond the schema. A baseline of 3 is appropriate.

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

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

The description clearly states the tool pulls fired events from the subscription feed and specifies the returned data (source, citation_uri, raw payload). While it distinguishes from its siblings by name and context, it does not explicitly differentiate from tools like 'events' or 'list_subscriptions', so a 4 is appropriate.

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 practical guidance on filtering by type and since, using mark_read, and mentions polling works fine. It also notes an alternative access via a direct GET endpoint. However, it lacks explicit when-not-to-use or alternative tool comparisons, justifying 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?

Describes multi-source fan-out, fallback behavior (GDELT→GNews), and soft-fail for USPTO. Explains return structure (changes grouped by source, total_changes count, citation URIs). Annotations already indicate read-only, idempotent, non-destructive, which the description does not contradict.

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 single paragraph that front-loads purpose with query examples, then details sources, parameters, and alternatives. Every sentence adds value, though the source list could be slightly trimmed. Overall very concise.

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

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

Despite no output schema, the description explains the return format adequately. It covers sources, fallbacks, and limitations (USPTO soft-fail). Suitable for a complex multi-source tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by clarifying `since` accepts ISO dates or relative shorthand (e.g., '7d', '30d') and suggesting defaults. Also explains `value` can be ticker or CIK. Exceeds baseline due to practical usage hints.

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

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

Description clearly states the tool is a 'change feed for a company in the last N days/weeks/months' and lists sources (SEC EDGAR, GDELT→GNews, USPTO). It starts with example queries and distinguishes from sibling 'entity_profile' by specifying when to use the alternative.

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 tells when to use this tool ('What's new', 'latest', etc.) and provides a direct alternative: 'Use entity_profile instead when you want the static profile'. Also gives guidance on the `since` parameter with examples.

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 key behaviors: key-value pair scoped by identifier, persistence details (authenticated users get persistent, anonymous 24h), and idempotency implied by annotations. Adds value 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?

Four sentences, front-loaded with purpose and usage, then technical details. No unnecessary words; every sentence earns its place.

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

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

For a simple two-parameter tool with no output schema, the description fully covers storage behavior, persistence, and integration with recall and forget.

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

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

Schema covers 100% with descriptions for key and value. Description adds naming conventions and value type context, enhancing 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's purpose: 'Save data the agent will need to reuse later' with a specific verb ('save') and resource ('data for later reuse'). It distinguishes from sibling tools like recall and forget.

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

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

Provides explicit guidance on when to use: 'when you discover something worth carrying forward' and examples such as 'a resolved ticker, a target address.' Also recommends pairing with recall and forget.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the description does not need to repeat these. The description adds unique value by noting that 'each call cascades through several lookup endpoints internally,' providing insight into internal complexity. It does not mention failure behavior or rate limits, but the annotation coverage is high, making additional disclosure less critical.

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 somewhat lengthy but well-organized with clear sections and examples. It front-loads with example queries and uses bullet-like structure for supported types. While every sentence adds value, it could be slightly more concise (e.g., the phrase 'auto-disambiguated' is somewhat redundant). Overall, it is effective and not overly verbose for the information conveyed.

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

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

Given no output schema, the description adequately explains return values for both entity types and includes citation URIs. It also covers input formats. However, it does not describe behavior for unresolvable inputs or pagination (not needed for a single-entity lookup). A 5 would require mention of edge cases like 'not found' handling. Still, for its complexity, it provides solid 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 description coverage is 100% (both parameters documented). The description goes far beyond by detailing what each entity type returns (e.g., company returns ticker + 10-digit CIK + company_name + citation URI; drug returns RxCUI + ingredient + brand + citation). It explains input formats (ticker, CIK, name, brand, generic). This provides substantial added value over the schema alone.

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: resolving user-spoken names to canonical/official identifiers. It provides specific example queries and explicitly lists supported entity types (company, drug) with their return values. The phrase 'Use FIRST whenever you have a name but need an ID' gives direct, actionable guidance, distinguishing it as the primary tool for name-to-ID resolution among siblings.

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

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

The description explicitly tells when to use the tool ('Use FIRST whenever you have a name but need an ID') and states it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use it or list alternative sibling tools that might also resolve entities, such as 'entity_profile' or 'compare_entities'. A 5 would require clearer exclusion 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: it probes each entity via 'ai_visibility_check', returns a 'ranked list with score, confidence, signal density per entity'. No contradiction with annotations. The description provides useful behavioral context beyond the annotations.

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

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

The description is relatively concise (4 sentences) and front-loaded with the main action. It efficiently conveys purpose, mechanism, and example usage. Could be slightly more structured but not overly verbose.

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

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

Given no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It covers all parameters and usage context. For a moderately complex tool with 4 parameters, it is sufficiently complete without missing critical information.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: 'First entry treated as the subject for narrative; rest are competitors' for 'entities', and explains 'context' disambiguates common names. This goes beyond the raw schema descriptions.

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

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

The description explicitly states 'Compare AI visibility across multiple entities side-by-side' and explains the probe-and-rank mechanism. It uniquely identifies the tool's function ('scan_competitor_ai_presence') and clearly distinguishes it from sibling tools like 'ai_visibility_check' (single probe) and 'compare_entities' (generic 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 clear usage context: 'Useful for competitive AI-marketing audits' with an example question. It implicitly indicates when to use (comparing multiple entities) but does not explicitly state when not to use or directly compare to all alternatives. However, the sibling list and description make differentiation possible.

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 the tool as readOnly, openWorld, idempotent, and nondestructive. The description adds critical behavioral details: it fans out to deps.dev and bundlephobia, handles partial failures gracefully, mentions bundlephobia's first measurement can take 5-30s, and specifies that sources_failed will list timeouts. This provides valuable context beyond the annotation hints.

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

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

The description is well-structured, front-loading the core purpose and then detailing output and failure modes. Every sentence adds value, though it is slightly long. It could be trimmed without losing information, but remains efficient.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers the input ecosystem, output fields (summary block, advisory details, links, alternative versions), and failure behavior (partial degradation, timeout behavior). This leaves little ambiguity 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 description coverage is 100%, so the baseline is 3. The description adds only minor value beyond the schema, such as confirming scoped packages are accepted. It does not significantly enhance understanding of the parameters.

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

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

The description clearly states the tool's purpose as a composite check for npm packages covering safety, popularity, and size. It uses a specific verb ('check') and resource ('npm package'), and distinguishes itself from siblings by being a one-call fan-out across multiple services.

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

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

The description explicitly tells when to use the tool (when asked about package safety/size/cost) and provides alternative for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This gives clear guidance on 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?

Annotations already declare readOnlyHint=true, etc. Description adds valuable context beyond annotations: embedding model (BGE-base-en), windowing (500-char overlapping), character cap (200K chars with truncation flag), and output details (character offsets, similarity scores). No contradictions.

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

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

Four well-structured sentences: first defines purpose, second gives usage context and pairing, third provides technical details. Every sentence adds value, 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?

Despite no output schema, the description fully covers input constraints, internal behavior (windowing, truncation), and output format (passages with offsets and scores). Complete for an agent to use correctly.

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

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

Schema coverage is 100%, but description adds extra meaning: for 'text' it clarifies max 200K chars and truncation, for 'query' gives concrete examples, and for 'limit' implies a default of 5. These enrich the schema descriptions.

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

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

The description uses specific verb 'semantic search' and resource 'inside a fetched record', clearly distinguishing it from sibling tools by stating it operates on text already pulled. It also mentions pairing with ask_pipeworx_grounded, further differentiating.

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 the tool: 'when the record is too big to cram into the prompt'. Also provides when-not guidance by explaining how it pairs with ask_pipeworx_grounded, offering a clear workflow.

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

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

The description goes beyond annotations by detailing the OAuth requirement, delivery channel constraints (e.g., SMS 10/day cap, webhook auto-disable after 10 failures), and webhook signing. This rich context helps the agent understand side effects and prerequisites, complementing the readOnlyHint=false and idempotentHint=true annotations.

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

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

The description is well-structured with clear sections for types, delivery channels, and examples. While it is somewhat dense, every sentence contributes value. It could be slightly more concise but remains effective for an AI agent.

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

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

Given the tool's complexity (3 parameters including nested objects, no output schema), the description is complete. It explains the return value (subscription id), all parameter details, constraints, and prerequisites. The agent has all necessary information to invoke the tool correctly.

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

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

The input schema is fully described in the tool description, with type-specific parameter structures (e.g., for sec_8k, polymarket_edge, etc.) and delivery channel options including examples and constraints. This adds significant meaning beyond the schema's basic type and required fields.

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This specifies the verb (create), resource (subscription), and the return value, distinguishing it from sibling tools like list_subscriptions or unsubscribe.

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

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

The description provides clear usage context, including the requirement for a Pipeworx OAuth account and supported subscription types with examples. It does not explicitly state when not to use this tool but implies that it is for creating new subscriptions, not for listing or deleting them. The context is sufficient for most cases.

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

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

The annotations already indicate readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral context: it returns example questions with exact tool+argument shapes, draws from live catalog, and can be focused by topic. This goes beyond annotations, providing useful transparency about what the tool does.

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 user queries and clearly structured. It is slightly long but every sentence adds value, defining purpose, categories, parameters, and usage order. No waste, but could be slightly more terse.

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

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

Given no output schema, the description adequately describes return values (category-bucketed examples with tool arguments). It covers the single optional parameter and usage. Annotations handle the safety profile. Almost complete, missing only potential return format details.

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

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

Schema coverage is 100% and the schema description already lists all valid topic values. The description repeats these values and adds the context of omitting for full spread, but adds limited new 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 identifies the tool as an onboarding entry point for learning what Pipeworx can do, listing specific categories and how it helps the agent. It distinguishes itself from sibling tools by stating 'Use this FIRST when you do not yet know what Pipeworx can do for you.' This is a specific verb+resource with clear differentiation.

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

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

The description explicitly states when to use the tool ('Use this FIRST when you do not yet know what Pipeworx can do for you') and how to call it (with no arguments for full spread, or pass topic). It does not explicitly exclude other tools but the usage context is clear, meriting a high score.

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

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

Annotations clearly indicate read-only, idempotent, non-destructive behavior. The description does not add extra behavioral context (e.g., pagination, rate limits), but annotations cover the main safety traits.

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?

Extremely concise single sentence with no wasted words. Could be slightly more informative without losing 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?

Despite good annotations, the description lacks details about output format, pagination, or how to handle large lists. The output schema exists but is not referenced.

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 67%, but the description adds no additional meaning to parameters. The required 'slug' parameter has no description in schema or 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 states it returns a transaction list for a collective, which is specific enough. However, it doesn't distinguish from siblings like 'collective', which may be the parent 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?

No guidance on when to use this tool vs alternatives or siblings. The description does not mention any preconditions 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?

Adds significant behavioral context beyond annotations: the row is deactivated (not deleted) and historical events remain available. This explains the non-destructive nature and data retention policy, which annotations only hint at via destructiveHint=false.

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

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

Two sentences, front-loaded with the core action. Every sentence adds essential information without redundancy.

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

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

Given a single parameter, no output schema, and sufficient annotations, the description fully covers what the agent needs: action, ownership constraint, and the deactivation behavior.

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

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

With 100% schema coverage, baseline is 3. The description adds value by clarifying that the 'id' parameter is a subscription id returned by 'subscribe', which helps the agent connect the tools.

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 'Cancel a subscription by id', specifying the verb 'cancel' and resource 'subscription'. The description also adds ownership enforcement, distinguishing it from related tools like 'subscribe' 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 clear usage context: cancel a subscription by id, with ownership enforcement. Although it doesn't explicitly list when not to use or alternatives, the context is strong enough to guide appropriate selection.

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

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

Annotations already indicate safe, non-destructive, idempotent behavior. Description adds detailed behavioral traits: replaces 4-6 calls, uses SEC EDGAR for financial claims, grounded pipeline for others, returns verdict with evidence and citation. No contradictions.

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

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

Description is informative but somewhat lengthy; however, each sentence adds value and the structure is logical, front-loading natural language triggers. Minor opportunity to trim redundant phrasing.

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?

Addresses complexity of two verification paths, return value details (verdict, actual value, citation, reasoning), and provides comprehensive guidance. No output schema but description covers return format adequately.

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

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

Schema coverage is 100%, but description significantly enhances understanding by explaining that tolerance_pct overrides implied wording tolerance, provides default cap (5), and gives usage examples. Adds value beyond schema.

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

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

Description clearly specifies the tool verifies factual claims using authoritative sources, distinguishes between company-financial and other claims, and lists natural language triggers. Differentiates from siblings by explaining unique dual-path processing.

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 ('check whether something a user said is factually correct') and describes internal routing logic. Could mention when not to use, but context is clear.

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