Newsdata

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint (all safe). The description adds valuable context: it makes calls to LLMs, and for Anthropic, the user pays directly (BYO key). It also describes the return format (per-model score, confidence, signals, raw_response + combined view), which goes beyond the 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 a single paragraph of ~80 words, but it is front-loaded with the core purpose and return structure. It conveys all necessary information without redundancy. Minor improvement could be splitting into two sentences for readability, but it remains concise and effective.

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

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

Given no output schema, the description adequately explains the return value (per-model details + combined view). It covers all parameters and their optionality, and provides use cases. The only gap is not specifying response size or pagination, but for a probing tool it is sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining the default model (Workers AI Llama-3.3-70b free), that '_apiKey' is only needed for Anthropic, and that 'context' helps disambiguate. This provides practical guidance beyond 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 clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score (0-100). It specifies the default model and optional Anthropic integration, and lists use cases (AI-marketing audits, pre-launch checks, competitive monitoring). This distinguishes it from sibling tools like 'scan_competitor_ai_presence' by focusing on cross-model visibility scoring.

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 context on when to use the tool (marketing audits, brand checks, competitive monitoring) and explains the default model and optional API key for Anthropic. It does not explicitly state when not to use it or compare to alternatives, but the use-case guidance is sufficient for an AI agent to determine applicability.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable operational behavior beyond annotations: it routes to sub-tools, fills arguments, returns structured answers with stable citation URIs, claims to work on every tier, and is a single fast call. This extra context helps an agent set expectations without contradicting any annotations.

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

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

The description is longer than ideal and repeats the 'prefer over web search' / 'even if web search could also answer' idea, plus 'START HERE' and 'default entry point' are redundantly stated. However, it is well-structured, front-loaded with the most important instruction, and every major section (scope, examples, alternatives) earns its place. It earns a 4 because it is dense but not bloated.

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

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

Despite no output schema, the description explains what the return looks like ('structured answer with stable pipeworx:// citation URIs'), enumerates covered domains, provides concrete examples, lists tier/performance characteristics, and explicitly names alternative tools for adjacent use cases. For a tool of this complexity, nothing critical is missing for correct selection and invocation.

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

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

Schema description coverage is 100%, so parameter semantics are fully documented in the schema. The description adds natural-language examples that illustrate valid questions, but it does not introduce any new parameter-level meaning beyond the schema. Per the baseline, a score of 3 is appropriate when the schema carries the full weight.

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

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

The description uses strong, specific verbs: 'routes the question,' 'fills arguments,' 'returns the structured answer with stable pipeworx:// citation URIs.' It clearly identifies the resource (a meta-tool spanning 5,718 tools across 1,496 sources) and differentiates itself from siblings like ask_pipeworx_grounded and deep_research by naming them and their distinct purposes.

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

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

It explicitly states when to use this tool ('Use whenever the user asks...', 'START HERE for most questions') and when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). This is clear, actionable routing guidance with no ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds meaningful context: it is a live experimental edge, candidates can be enabled at any time, it currently matches ask_pipeworx exactly, and it 'falls back to nothing' as a full working router rather than a stub. This goes beyond the structured hints and gives a clear behavioral model.

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

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

The description is dense and front-loaded with the tool's identity and relationship to ask_pipeworx. Each sentence adds useful operational information, though phrases like 'identical universal router' alongside 'same 5,718 tools, same arguments, same response shape' are slightly redundant. Overall it is appropriately sized for a beta tool with an important distinction.

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

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

For a router tool with no output schema, the description covers the essential context: what it routes to, why it is experimental, current status, how to use it, and that it is not a fallback. The 'same response shape' reference provides return-value context by analogy to ask_pipeworx. It could be improved by explicitly describing the output shape, but the current coverage is strong.

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

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

Schema coverage is 100%, with each parameter described as an alias for 'question' and a clear natural-language description on the question field itself. The description says 'same arguments' but adds no semantic detail beyond what the schema already provides. Baseline 3 is appropriate because the schema handles parameter meaning fully.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router that dispatches to 5,718 tools. It explicitly states it uses the same arguments and response shape, and differentiates itself from the stable sibling by its experimental routing edge. An agent can understand what this tool does and how it differs from ask_pipeworx without opening the schema.

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 to use it like ask_pipeworx 'when you want the newest routing' and notes that results are compared against the stable router. It also clarifies that no candidate is active right now, so behavior currently matches the stable tool. However, it lacks an explicit when-not-to-use statement, though the contrast with the stable router implies the stable alternative.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds meaningful behavioral context beyond these: it reveals the extraction-only constraint, the exact refusal reasons, the extra LLM call cost, and the structured return shape. This goes well beyond what annotations alone convey.

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

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

The description is relatively long but densely informative: it front-loads the core purpose, then explains behavior, return values, refusal cases, use cases, and cost trade-off. Every sentence contributes actionable information for selecting and invoking the tool correctly. No filler is present.

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

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

Despite having no output schema, the description fully documents the return payload and explicit refusal reasons, which is essential for a tool that must not hallucinate. It covers success and failure modes, use cases, cost implications, and routing behavior. With rich annotations and 100% parameter coverage, nothing critical is missing.

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

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

The input schema already has 100% description coverage, explaining that all six parameters are aliases for the natural-language question. The tool description does not add any further parameter-level semantics beyond mentioning that the tool 'fills arguments' internally. Baseline 3 is appropriate because the schema carries the load.

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

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

The description clearly states this is a hallucination-resistant, grounded answer mode for high-stakes reads, and explains it routes to tools like ask_pipeworx but extracts answers strictly from tool results. It explicitly distinguishes itself from ask_pipeworx by emphasizing evidence and refusal behavior. A specific verb, resource, and unique behavior are all present.

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 to use this tool whenever an answer will be quoted, cited, or acted on and the agent must not invent facts, while also instructing to prefer ask_pipeworx for casual lookups due to the extra LLM call cost. This gives clear when-to-use and when-not-to-use guidance relative to the sibling tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds extensive behavioral details: low-confidence short-circuit with status field, closed market handling, wide spread tradeability, resolution-rule risk parsing, news fields with fallback info, and parent event extractor. No contradictions with annotations. The description significantly supplements the annotations.

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

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

The description is long but filled with essential details. It is front-loaded with purpose and usage, then dives into technical specifics. Given the complexity of the tool (multiple classifiers, fan-out patterns, response shapes), every sentence earns its place. Could be slightly more concise but well-structured for the information density.

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

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

The description covers all critical aspects: input formats, output structure, edge cases (low confidence, closed markets, illiquid spreads), resolution rules, parent events, news fallbacks, and safety mechanisms. No output schema exists, but the description thoroughly documents response shapes. It is fully complete for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100%, baseline is 3. The description adds meaningful context beyond the schema: explains depth as 'quick = 2-3 evidence sources, thorough = full fan-out', market as accepting slug/URL/text, and include_raw with recommendation for false. Also provides examples and functional implications (size reduction). This adds value beyond 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 clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). The verb 'research' and resource 'Polymarket bet via Pipeworx data' are specific and distinguishable from sibling tools like ask_pipeworx or 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?

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and provides fan-out examples for various bet types. It doesn't explicitly list when not to use or name alternatives, but the context from sibling tools and the detailed usage examples provide sufficient guidance.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds details like handling off-calendar fiscal years, sorting by primary metric, and returning citation URIs, with no contradictions.

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

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

The description is front-loaded with common query phrases and is informative, but slightly verbose. Could trim redundant parts while preserving all necessary details.

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

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

Given no output schema, the description adequately explains return format (paired data with citation URIs), sorting behavior, and the range of entities covered, making it complete for an agent.

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

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

Schema coverage is 100% with descriptions, and the description elaborates on what each type retrieves (e.g., company pulls revenue/net income/cash/debt; drug pulls FAERS/FDA/trial counts), adding significant meaning.

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 performs side-by-side comparisons of 2–5 companies or drugs, specifying what data is pulled for each type. It distinguishes itself from siblings by advising preference over sequential single-pack lookups.

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

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

Explicitly lists example queries and when to use ('ALWAYS PREFER over sequential single-pack lookups'). Provides clear context and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the agent knows it's safe. The description adds value by detailing the output fields (title, description, link, source, publish date, category, country), which aids understanding of what the tool returns.

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: three sentences that front-load the purpose, then detail filtering and output, ending with an example. Every sentence adds value without unnecessary elaboration.

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 compensates by listing return fields. It covers filtering options and provides an example. It is complete enough for an agent to decide if this tool meets its needs, though a note on pagination or limits could enhance 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?

The input schema covers all 4 parameters with descriptions (100% coverage). The description reinforces the meaning by providing examples and clarifying that `coin` accepts comma-separated tickers, which goes beyond the schema's description.

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

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

The description clearly states 'Get the latest cryptocurrency news headlines and articles.' It specifies filtering by keyword, coin ticker(s), and language, and mentions return fields. This distinguishes it from sibling tools like `latest_news`, which is likely general news.

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 suggests usage through examples and mentions filtering capabilities, but does not explicitly compare to alternatives like `latest_news` or `news_sources`. Users can infer when to use it based on crypto focus, but explicit guidance would be beneficial.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by disclosing account requirements, depth-specific behavior (gap recovery, contradiction scan), parallel decomposition into facets, the structure of the findings packet (verbatim evidence, confidence, source, fetched_at, citations), the explicit gaps[] handling (never invents), second-hop iteration, semantic excerpting, and expected latency (15-90s). It even clarifies citation_uri resolvability. This is comprehensive behavioral disclosure that fully complements, and never contradicts, the annotations.

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

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

The description is quite long, but every sentence carries essential information: account requirements, usage alternatives, internal mechanics, citation behavior, time estimates. It is front-loaded with the most critical info (account requirement, fallback to ask_pipeworx) and then layers details. Slightly verbose and stream-of-consciousness, but not padded. It could benefit from clearer paragraph breaks, but remains efficient relative to its coverage.

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 (2 params, no output schema), the description covers all critical aspects: prerequisites (account, paid tier), alternatives, scope, behavioral details, latency, gap handling, and citation specifics. An agent can effectively decide whether to use this tool and how to set parameters without needing additional context. The absence of an output schema is compensated by the detailed description of the findings packet.

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

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

Although the input schema already provides full 100% coverage for both parameters (question and depth), the description adds meaningful context beyond the schema: it explains that depth:'thorough' requires a paid plan, gives time expectations per depth, and clarifies the decomposition behavior tied to depth. It also describes how the 'question' parameter should be phrased (natural language, broad/multi-part is fine). This enriches the schema without redundancy.

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

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

The description clearly states the tool's purpose: grounded, multi-source research across structured data sources (SEC, FRED, FDA, etc.) in one call. It explicitly distinguishes itself from open-web search and names the alternative ask_pipeworx for single lookups, making it easy for an agent to select this tool for broad, multi-part structured-data questions. The verb 'research' and resource '1496 structured data sources' are specific and unambiguous.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: it names ask_pipeworx as the alternative for single lookups and for breaking/colloquial current-news topics, explaining that deep_research returns empty gaps[] for such topics. It also explains the benefit for multi-step questions via depth levels. This is optimal routing guidance, leaving no 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 provide readOnlyHint, idempotentHint, destructiveHint=false. Description adds that results are ready to call without second schema lookup, which is valuable 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 fairly comprehensive but not overly long. It front-loads purpose and usage, though some sentences could be tighter. Still 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 no output schema, the description adequately explains return structure (names, descriptions, schemas). It covers input, purpose, and usage context completely for this 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% with descriptions for each parameter, including aliases. The description adds overall context but does not significantly extend parameter meaning 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 it's for finding tools by describing data or task, enumerates many domains, and specifies it returns top-N tools with full schemas. It distinguishes from sibling tools by focusing on discovery.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set', which provides clear usage context and when-not-to-use (direct queries).

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds details: fans out across multiple sources, parallel call, patent API sunset soft-fail, news fallback. 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?

Front-loaded with examples and usage guidance; every sentence adds value but slightly long. Could be tightened.

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

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

Despite no output schema, description details return fields (cik, filings, fundamentals, patents, news, LEI) and mentions limitations (patent sunset, no names). Comprehensive for a complex tool.

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

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

Schema coverage 100% but description adds meaning: explains value can be ticker or CIK, names unsupported, includes examples. Baseline 3, plus extra 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?

Description clearly states the tool provides a holistic cross-source profile of US public companies, with explicit use case examples like 'Tell me about X' and distinction from single-pack lookups.

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

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

Explicitly states when to use (holistic view), when not to use (names not supported), and provides alternative (resolve_entity for names).

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 destructiveHint=true; the description adds that it 'clears sensitive data', reinforcing the destructive nature. No contradictions. Could mention idempotent behavior but not required.

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

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

Two concise sentences: first defines the action, second provides usage guidance. No fluff; 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?

Given the tool's simplicity (single parameter, no output schema), the description covers all necessary information: action, usage context, and related tools.

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

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

Schema coverage is 100% and describes the 'key' parameter sufficiently. The description does not add additional semantic information beyond the schema, so 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?

Clearly states 'Delete a previously stored memory by key', with a specific verb and resource. Distinguishes from sibling tools 'remember' and 'recall' by indicating deletion.

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

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

Explicitly states when to use: when context is stale, task done, or to clear sensitive data. Also suggests pairing with 'remember' and 'recall', providing clear 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?

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. 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 concise, front-loaded with the main purpose, and every sentence adds value. 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?

Despite no output schema, the description explains the output format and process. All necessary information for a 2-param tool is covered.

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

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

Schema coverage is 100%, baseline 3. The description marginally adds to url parameter by stating 'Fetches the page, extracts...' but does not elaborate on max_links beyond schema. Adequate for coverage.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and target. It distinguishes from siblings by focusing on a specific format and use case.

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

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

The description lists explicit use cases (client indexing, personal project, competitor audit). It is clear when to use, though it does not explicitly mention when not to use or alternatives.

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

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

Beyond the readOnlyHint annotation, the description discloses return fields (title, description, link, source, publish date, category, country), pagination via nextPage token, and filtering behavior (business category filters out SEO/crypto-promo content). It also warns about zero results for wrong category guesses, adding significant behavioral context.

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

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

The description is compact but information-dense, with a clear flow: purpose, filters, critical note, return fields, pagination, examples. Every sentence adds distinct value, and the front-loaded first sentence immediately establishes the tool's core function.

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

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

No output schema exists, so listing return fields is essential—done. Pagination, parameter usage, and edge-case warnings (zero results) are covered thoroughly. With 6 optional parameters and rich examples, the description fully equips an agent to use the tool correctly in varied scenarios.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by illustrating parameter combinations with examples (query+category, query+country+category+language) and by emphasizing the business category behavior, which is critical for effective use. However, it doesn't deeply elaborate on type formats beyond what the schema already explains.

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

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

The description opens with a specific verb+resource: 'Get the latest global news headlines and articles' and clearly enumerates coverage areas (world news, breaking news, business/financial/stock-market). It distinguishes itself from sibling tools like crypto_news by stating 'global' and including multiple categories, making the scope unmistakable.

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

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

Provides explicit when-to-use guidance with capitalized 'IMPORTANT' instruction for stock-market queries to pass category 'business', plus concrete examples for world market news and election news. It also implies alternatives by noting category behavior and omitting crypto, which differentiates from sibling crypto_news.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the list of returned fields but does not disclose additional behavioral traits like pagination or rate limits. This is acceptable given annotations cover safety.

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

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

Two concise sentences: the first states purpose and return fields, the second provides usage guidance. Every sentence adds value with no redundancy.

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

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

The description lists all relevant return fields and provides usage context. Given the low complexity (no output schema, one optional parameter), it is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no further meaning to the 'include_inactive' parameter beyond what is already in the schema.

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

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

The description clearly states 'List the caller's active subscriptions', identifying the specific verb and resource. It also enumerates the fields returned, distinguishing it from sibling tools like subscribe and 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 explicitly advises when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' While it doesn't list negative use cases, the guidance is direct and helpful.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds return fields and example but doesn't contradict annotations.

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

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

Two sentences plus example, no filler. Efficiently conveys purpose, filters, return fields, and usage hint.

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

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

For a simple read-only listing tool with no output schema, description covers input filters, return fields, and provides an example. Annotations cover behavioral traits.

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. Description adds example call and global context, but parameters are already well-documented.

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 'List available global news sources' with specific verb and resource. Distinguishes from siblings like crypto_news and latest_news.

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?

Describes use case: 'useful for discovering which outlets cover a given region or topic.' No explicit when-not-to-use, but context implies search for sources rather than articles.

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

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

Annotations already mark readOnlyHint false, so the write nature is known. The description adds beyond annotations by disclosing the claim_token workflow (no account needed, returns token, can be passed back later), rate limits (5/day), and that feedback is free and doesn't count against quota. This enriches the agent's understanding of side effects and constraints.

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

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

The description is a single dense paragraph but every sentence contributes distinct information. While it could be broken into subsections for readability, the front-loaded purpose and seamless integration of usage and constraints make it effective without excess verbiage.

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 feedback tool with no output schema and a parameter object, the description covers the entire interaction lifecycle: what to report, how to report it, what happens when no account exists, how to retrieve status later, and how to avoid misdirected reports. Rate limits and the 'don't paste user prompt' guideline round out a complete, self-contained explanation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by instructing the agent to describe issues in terms of Pipeworx tools/packs and to avoid pasting end-user prompts, which refines how to populate the 'message' and 'context' fields. It also explicitly explains the claim_token parameter's purpose without relying solely on the schema.

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

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

The description starts with a specific verb ('Tell') and resource ('Pipeworx team'), and clearly defines the tool's scope: reporting broken/missing/needed functionality. It distinguishes this from all sibling tools (research/news entity tools) by focusing on feedback rather than data retrieval or analysis.

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

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

Provides explicit when-to-use categories (bug, feature/data_gap, praise) and, crucially, a when-not-to-use condition: if the tool came from a different MCP server, direct the user to file elsewhere. Also includes token-based follow-up usage and rate-limit context, making the conditions for use unambiguous.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false. Description adds caching behavior (5min-1h), data derivation (CF analytics-engine), and privacy assurance (no PII), providing behavioral details 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, no fluff, front-loaded with purpose. Slightly verbose with 'Useful for:' enumeration but still 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?

Covers all aspects: return content (top tools, packs, call volume), window options, use cases, caching, privacy. No output schema needed as behavior is clear.

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

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

Schema coverage is 100% with one parameter. Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' going beyond the enum description to help agent choose.

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?

Explicitly states it returns trending tools, packs, and call volume on Pipeworx over three time windows. Distinguishes from siblings like discover_tools by focusing on real-time popularity derived from AI agent calls.

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?

Lists three specific use cases (discovering hot data sources, confirming canonical tools, aligning use cases). Does not explicitly state when not to use it, but the use cases provide clear context for appropriate 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, openWorldHint, idempotentHint, and destructiveHint as false. The description adds rich behavioral context: details on semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), fill check against live CLOB depth, and output structure. 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 front-loaded with the core purpose and then expands logically into mode details. While lengthy, every sentence adds value for a complex tool. Minor redundancy in parameter descriptions could be trimmed, but overall 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?

Without an output schema, the description thoroughly explains return values and internal logic: opportunities array fields, partition_check structure, fill_check details, and edge cases like skipped_low_similarity and placeholder filtering. It is complete for a two-mode 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% with descriptions for both parameters. The description adds meaning by explaining the difference between event and topic modes, providing example inputs (e.g., 'fed-decision-may-2026'), and detailing internal processing. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (trending_scan, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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 guidelines are provided: 'Call with NO args for a trending_scan... pass event for... pass topic for...' The description recommends when to use each mode, explains cross-event advantages, and directs to polymarket_fill_risk for custom sizing, offering clear when-to-use vs alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds extensive behavioral detail: caching at KV level (1h), output structure (by_segment, _diagnostics), edge calculation specifics (slippage, Kelly), and model families. 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 dense but well-structured: purpose first, then model details, response structure, knobs. Every sentence adds value, though it could be slightly more concise. It earns its length.

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

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

Given 9 parameters, no output schema, and full annotations, the description is remarkably complete. It explains the three segments, diagnostics, caching, and edge calculations. A human or AI agent can fully understand the tool's 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining parameter effects (e.g., slippage_pp: 'Polymarket has zero trading fees...'; min_liquidity: 'drop thin-book opportunities'). This adds value for an AI 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 clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for 'what should I bet on today' and distinguishes itself from siblings like polymarket_arbitrage.

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

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

The description provides explicit context for use ('what should I bet on today') and notes that Fed bets surface but are excluded due to unreliable signal. It does not explicitly mention when not to use or alternative tools, but the context is clear.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds substantial behavioral details: data sources (daily snapshots on cache-miss), output structure (tracked[], expired[], snapshot_dates), and field explanations (edge_pp_net signed by direction, decay, lifespan). 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 well-structured with a clear purpose statement upfront, followed by argument details and response explanation. It is slightly verbose but packs necessary information. Could be tightened slightly without losing clarity.

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

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

Given no output schema, the description thoroughly explains the output fields (tracked[], expired[], snapshot_dates) and their meaning. Includes limitations (60-day TTL, cache-miss gaps). Covers all necessary contextual details for an agent to understand usage and results.

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

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

Schema covers both parameters (days, window) with descriptions. The description restates defaults and provides context (e.g., 'snapshot family' for window) but does not add significant new meaning beyond the schema. Baseline 3 for 100% 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 the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses specific verbs (answers, tracks) and resource (edge persistence over time). It distinguishes from sibling tools like polymarket_edges by focusing on time-series decay rather than current edges.

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

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

The description gives explicit context for when to use the tool (assessing edge age and decay, differentiating fresh vs old edges). It implies alternatives (polymarket_edges for current data) but does not explicitly state when not to use it. The 'LIMITS' section adds practical 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: walks the ladder, returns specific fields (top_of_book, slippage, verdict), and details risks like thin legs and forced directional risk. No contradiction with annotations.

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

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

The description is information-dense but somewhat lengthy. It uses structured sections (REQUIRES, SINGLE-MARKET, BASKET) which aid readability. Some sentences could be more concise, but overall it earns its length by providing necessary detail.

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

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

Given the tool's complexity (two modes, multiple return fields, risk warnings), the description is comprehensive. It explains both modes, return values in detail, and contextual risks. No output schema exists, so the description must cover return values, which it does 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?

Schema descriptions cover 100% of parameters, providing baseline 3. The description adds usage context beyond schema, such as default size_usd=1000 and clamp 10-1,000,000, and explains the auto-detection of side in basket mode. While schema covers basics, description enriches with practical constraints.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, detailing what each mode does and returns. The verb+resource are specific and distinct from siblings.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills create directional risk), offering alternatives implicitly through sibling tool names.

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

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

Beyond the readOnly/idempotent annotations, the description thoroughly discloses the tool's caveats: compatibility_warning and compatibility_codes may both be non-empty, unclassified legs are never paired, and premapped_pairing_unverified is always set in topic mode. It also explains skipped cross-type/subtype logic and warns that pre-mapped does not imply tradeable, giving the agent an accurate model of the tool's reliability.

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 deliberately structured with labels such as TWO MODES, RESPONSE, SAFETY FIELDS, and Codes. It front-loads the core purpose and then covers important safety behavior in a readable way. It could be tightened slightly, but most sentences carry distinct 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?

With no output schema and three optional parameters, the description is essentially the full contract. It covers response shape, warning codes, skipped-pair logic, temporal alignment, and real-world caveats, so an agent has everything needed to call the tool and interpret its results correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds genuine value by explaining which parameter selects which mode, that kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides, and exactly what the topic parameter's shortcuts are. This goes beyond the property descriptions in the schema.

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

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

The description opens with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It also explains two operational modes, making the resource and action unmistakable. However, it never explicitly distinguishes this tool from similarly named siblings like polymarket_arbitrage, so it stops short of full sibling differentiation.

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

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

The description gives clear when-to-use context for both modes: topic shortcuts for pre-mapped macros and explicit ticker/slug pairings for custom comparisons. It cautions that most pre-mapped topics currently return compatibility warnings, which helps set expectations, but it does not name alternatives or provide exclusion conditions.

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

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

Consistent with readOnly and idempotent annotations. Adds scope detail (by identifier) and pairing with remember/forget, though no mention of rate limits or exact key format.

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

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

Very concise: two sentences and a clause. Every sentence adds unique value, 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?

For a simple recall tool with full annotation support, the description covers purpose, usage, scope, and pairing with sibling tools. No gaps.

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

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

Schema coverage is 100% with one optional 'key' parameter. Description adds meaning by explaining that omitting key lists all keys, and mentions scoping.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys. It explicitly names sibling tools 'remember' and 'forget', distinguishing it well.

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 use cases like retrieving a target ticker or research notes. Mentions scoping by identifier but doesn't explicitly state when not to use it.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds valuable behavioral info: the mark_read parameter flags events as read, affecting future calls. This goes beyond annotations and is crucial for correct use.

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?

Five sentences, well-structured, front-loaded with clear purpose. Every sentence adds value; 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 no output schema, description covers return fields, filtering, mark_read, and alternative endpoint. Lacks pagination details and error handling, but sufficient for a read 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%, but description adds examples (e.g., 'sec_8k' for type) and explains mark_read's effect, enriching 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 it pulls fired events from the subscription feed and returns recent alerts with specific fields. It distinguishes from sibling tools like list_subscriptions (which manages subscriptions) by focusing on event retrieval.

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

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

The description provides context: polling works fine, and mentions an alternative endpoint for scripts/dashboards. However, it doesn't explicitly state when not to use this tool or compare it to siblings beyond the alternative.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds multi-source fan-out, fallback logic, soft-fail behavior, and return structure with citation URIs, all consistent with annotations.

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

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

Description is a single paragraph but front-loaded with purpose and use cases. It's informative and avoids fluff, though could be more structured for easier parsing.

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 (multi-source, fallback, no output schema), description covers return format (changes grouped by source, counts, URIs) and explains when to use alternative tool. Complete for read-only monitoring 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 already describes all 3 parameters clearly (100% coverage). Description goes beyond with example values, relative shorthand explanations, and typical monitoring advice ('Use 30d or 1m'), adding useful context.

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 provides a change feed for a company from SEC EDGAR, GDELT/GNews, and USPTO within a time window. It also distinguishes from sibling tool entity_profile which provides a static profile.

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

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

Explicitly gives example queries and when to use entity_profile instead. Also explains fallback behavior (GNews when GDELT rate-limited) and soft-fail for USPTO.

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

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

Annotations indicate write (readOnlyHint=false), idempotent, non-destructive. Description adds scoping, persistence (auth vs anonymous), which goes 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?

Three sentences, front-loaded purpose, no waste. Each sentence contributes essential information.

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

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

No output schema, but description adequately covers usage context. Could mention overwrite behavior, but idempotency hint covers it.

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% of parameters. Description gives examples but does not add new semantics beyond what schema provides. Baseline score appropriate.

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

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

Clearly states 'save data the agent will need to reuse later' with concrete examples (ticker, address, preference). Distinct from siblings recall/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?

Explicitly says 'Use when you discover something worth carrying forward' and pairs with recall/forget. No explicit exclusions 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.

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

The description goes well beyond the readOnly/idempotent/openWorld annotations by disclosing internal cascading lookups, graceful degradation when LEI/FIGI sources are unavailable, explicit `unresolved` output behavior, and the `figi_candidates` ambiguity handling. It also explains that non-equity instruments resolve even without tickers. This is rich behavioral context that annotations cannot convey.

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

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

The description is front-loaded with purpose and usage, and it is well-organized by entity type. However, it is quite long and includes redundant illustrative examples and parenthetical explanations that could be trimmed. Despite the verbosity, most content earns its place given the tool's complexity.

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

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

The description is complete for a complex tool with no output schema: it explains identifier sources, resolution behavior, ambiguity handling, unsupported cases, and failure semantics. An agent has enough context to decide when to call the tool and what to expect in the response. The detailed notes on ownership resolution and ISIN-to-LEI mapping cover edge cases that would otherwise be opaque.

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

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

Although schema description coverage is 100%, the description adds significant meaning beyond the schema. It explains what `value` should be for each type, gives concrete examples (AAPL, 0000320193, ozempic), and warns against passing full noun phrases for bonds. This prevents common misuse and materially helps an agent construct valid calls.

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

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

The description states a specific action: resolve a user-spoken name to canonical/official identifiers that other tools require. It gives a rich set of concrete examples (ticker, CIK, LEI, RxCUI) and distinguishes this tool from ID-consuming siblings. It also clarifies supported entity types, 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 instructs 'Use FIRST whenever you have a name but need an ID,' which is a strong when-to-use signal. It does not name alternative tools or explicitly state when not to use it, but among the listed siblings none directly competes with the name-to-ID resolution role. The guidance about passing 'ENTITY NAME ONLY' adds practical usage nuance.

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?

Description adds behavioral details beyond annotations: probes via ai_visibility_check, ranks by score, treats first entity as subject. Annotations already cover safety (readOnly, idempotent, non-destructive), so additional context is valuable.

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

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

Three concise sentences front-loaded with purpose and key behavior. 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, description specifies return fields (score, confidence, signal density). Parameters are fully covered. Slight gap: no mention of error handling or edge cases (e.g., empty results).

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

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

Schema coverage is 100%, but description adds meaning: explains that 'entities' first entry is treated as subject for narrative, and clarifies purpose of optional fields (e.g., context disambiguates names).

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 specifies the action ('compare', 'rank') and resource ('AI visibility across multiple entities'), clearly distinguishing from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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 mentions use case ('competitive AI-marketing audits') and provides a concrete example question, but does not state when not to use or list explicit alternatives beyond the sibling context.

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

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

Annotations already convey read-only, idempotent, and non-destructive nature. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will report timeouts. This enriches 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 moderately detailed yet efficient. It front-loads the composite purpose, then covers usage, output summary, ecosystem scope, and error handling. Every sentence adds value, though slightly longer than minimal.

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

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

Despite no output schema, the description comprehensively lists return fields (summary block with is_latest, license, bundle sizes, etc.), per-advisory detail, links, and alternative versions. It also covers performance caveats and partial failure handling, making it fully informative for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds useful context: version defaults to latest when omitted, and scoped packages like '@types/node' are accepted. This clarifies behavior 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 defines the tool as a composite check for evaluating npm packages across deps.dev and bundlephobia, addressing questions like safety, popularity, and size. It explicitly distinguishes itself from sibling tools by noting the npm-only scope and directing other ecosystems to deps.dev:version.

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

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

The description provides explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also clarifies when not to use it (non-npm ecosystems) and suggests an alternative (deps.dev: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?

The description adds significant behavioral context beyond annotations: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K chars cap with truncation flag. Annotations already indicate safety (readOnly, idempotent, non-destructive), and the description complements this with implementation details. No contradiction.

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

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

The description is approximately 100 words, well-structured with a clear first sentence followed by usage details and technical specifics. Every sentence adds value without redundancy.

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

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

Given no output schema, the description explains the return type (top-N passages with character offsets and similarity scores) and covers truncation behavior. For a 3-parameter semantic search tool, this is comprehensive and leaves no major gaps.

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

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

Schema coverage is 100% with clear descriptions for all parameters. The description reinforces the purpose of each parameter, adds examples for the query parameter, and notes the max size for text. This enhances understanding beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, using specific verbs like 'search inside' and 'pass the text... plus a query; get back passages'. It distinguishes from siblings like ask_pipeworx_grounded, which grounds over passages, making the purpose unambiguous.

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

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

The description explains when to use: when a record is too large for the prompt, to save context, and to return relevant passages with offsets for verification. It also suggests pairing with ask_pipeworx_grounded. While it doesn't explicitly state when not to use, the context is clear and helpful.

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

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

The description adds behavioral context beyond annotations: it mentions the need for an OAuth account, persistence, and delivery limits (10 SMS/day). Annotations already indicate idempotence and non-read-only nature; the description complements these without contradiction.

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

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

The description is detailed and well-structured, starting with the main action and then elaborating on types and delivery. While lengthy, every sentence adds necessary information. Slightly verbose but not wasteful.

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

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

Given the complexity of multiple subscription types and delivery options, the description covers all essential aspects: return value (subscription ID), auth prerequisites, type-specific parameters, and delivery constraints. No output schema is present, but the description adequately addresses return value expectations.

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, but the tool description goes significantly further by providing concrete examples for each subscription type (e.g., sec_8k with item codes, polymarket_edge with topic) and detailed guidance on delivery channel parameters (email, SMS, webhook with HMAC signing). This adds substantial value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream' and specifies it returns a subscription ID. It lists supported types and delivery channels, distinguishing it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides explicit usage context: requires a Pipeworx OAuth account, explains types with examples, and details delivery options with constraints (e.g., SMS cap, phone verification). It does not explicitly state when not to use this tool or compare to alternatives, but the guidance is sufficiently clear.

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

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

Annotations already mark readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/true/true/false. The description adds behavioral context: output structure (category-bucketed with tool+argument shapes), dynamic content from live catalog, and the effect of passing 'topic'.

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-structured: starts with alternative phrasings, then purpose, output, usage. Every sentence adds value, but could be slightly more concise without losing information.

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

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

Given no output schema, the description fully explains what the tool returns (categories, example questions with tool shapes) and how to use it. It covers the core purpose, input behavior, and when to use, making it complete for an onboarding 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% with one optional parameter. The description elaborates on the 'topic' parameter by listing allowed values and explaining that omitting it returns a cross-category spread, adding value beyond the schema's generic description.

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

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

The description clearly states the tool returns categorized example questions with tool+argument shapes. It distinguishes itself as the onboarding entry point for new users, differentiating from sibling tools like ask_pipeworx or entity_profile.

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

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

Explicitly advises to use this tool first when unfamiliar with Pipeworx, and provides clear instructions: call with no arguments for full spread or pass a topic to focus. Does not mention when to avoid, 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.

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

Discloses that rows are deactivated (not deleted) and historical events remain available via 'recent_alerts', beyond annotations. Ownership enforcement is also noted.

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 core action, second adds critical behavioral detail. Efficient and well-structured.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, and side effects. Annotations complement well. 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 defines one parameter 'id' with description 'Subscription id (uuid) returned by subscribe.' Description adds no extra meaning, and schema coverage is 100%, yielding baseline 3.

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

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

Description explicitly states 'Cancel a subscription by id.' using clear verb+resource pair. Distinguishes from sibling 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?

States ownership enforcement ('you can only cancel your own subscriptions'), implying when to use. Does not explicitly list alternatives but provides clear context.

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

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

Beyond the readOnly/openWorld/idempotent hints, the description adds vital behavioral nuance: 'could_not_verify means the check did not happen... it is NOT evidence for or against the claim,' and distinguishes unsupported. It also discloses the internal routing logic and that it 'Replaces 4–6 sequential calls,' giving callers confidence about safety and semantics.

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

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

The description is long but well-structured, using trigger phrases, a clear use-case statement, routing details, and an important caller warning. Each sentence carries substantive information with no filler, so the length is justified by the tool's complexity.

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

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

There is no output schema, so the description must explain return values—and it does: verdicts, actual value with citation, reasoning, and the special meanings of could_not_verify and unsupported. The routing logic and purpose are fully covered, making the description self-sufficient for correct invocation.

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

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

The input schema already provides complete descriptions for both parameters (claim and tolerance_pct), including defaults and override behavior. The description adds little beyond what the schema says, so the baseline of 3 is appropriate.

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

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

The description opens with concrete trigger phrases ('Is it true that…', 'fact check') and then defines the tool as 'natural-language claim verification against authoritative sources.' It clearly differentiates from sibling tools by focusing on verifying factual claims, and even specifies a structured fast path for company-financial claims.

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

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

The description explicitly states when to use it: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains routing (SEC EDGAR for financial claims, grounded pipeline otherwise), though it does not name sibling tools as alternatives or provide explicit exclusion criteria.

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