Finnhub

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

The description discloses behavioral traits beyond annotations: default model (Workers AI Llama 3.3 70b), optional Anthropic probe with BYO key (billing details), and return structure (per-model {score, confidence, signals, raw_response} + combined view). This adds rich context that annotations alone (readOnlyHint, openWorldHint, idempotentHint) do not cover.

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

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

The description is two sentences long, front-loaded with the main action and output, then details. Every sentence is substantive: purpose, default model, optional Anthropic call, return structure, and use cases. No wasted words.

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

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

Given the tool's complexity (4 params, no output schema), the description adequately covers usage, parameters, and return format. It lacks mention of error handling or rate limits, but annotations (idempotent, readOnly) mitigate those concerns. A minor gap for completeness.

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

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

Schema coverage is 100%, but the description adds extra value: it explains the 'models' parameter's supported values and default behavior, the '_apiKey' requirement and billing model, and provides a usage example for 'context'. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility. It specifies the verb 'probe' and 'score', the resource (LLMs), and the output (0-100 score). It distinguishes itself from sibling tools like 'deep_research' or 'ask_pipeworx' by focusing specifically on visibility measurement across multiple models.

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

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

The description provides clear usage contexts: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use this tool versus alternatives, but given the sibling tools, the contexts are sufficiently distinct. A minor gap is the lack of exclusion guidance.

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

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

Annotations already establish readOnlyHint, openWorldHint, idempotentHint, and non-destructiveness. The description adds meaningful behavioral context beyond those: routing through 5,708 tools, filling arguments, returning citation URIs, working 'on every tier,' and being 'one fast call.' It does not contradict the annotations and gives a fuller operational picture.

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 and dense, but it is front-loaded with the key directive 'PREFER OVER WEB SEARCH' before moving into scope and examples. Some redundancy exists, such as restating the preference for web search after already saying 'PREFER OVER WEB SEARCH,' but the structure is scannable and the examples earn their place.

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

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

For a broad, complex meta-search tool with no output schema, the description supplies nearly everything needed to invoke it correctly: domain coverage, trigger phrases, example queries, citation format, sibling escalation paths, and performance expectations. It even explains how breaking-news queries are handled. No critical context is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents the single required question parameter and its aliases. The description adds useful example queries like 'current US unemployment rate' and 'Apple's latest 10-K,' but it does not add new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a clear verb and resource: it 'Routes the question to the right one of 5,708 tools' and 'returns the structured answer with stable pipeworx:// citation URIs.' It also sharply distinguishes itself from siblings ask_pipeworx_grounded and deep_research, making its role as the default general-purpose entry point 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 gives explicit when-to-use guidance: 'Use whenever the user asks...' and 'START HERE for most questions.' It also names alternatives with the condition for escalation: use ask_pipeworx_grounded for 'a hallucination-resistant single answer with verbatim evidence + confidence' and deep_research for 'a broad/multi-part question.' This fully replaces guesswork.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses genuinely important behavioral nuances: candidate routing changes are enabled live, the last candidate was retired, the tool currently matches ask_pipeworx exactly, and there is no fallback—it is a full working router. This is exactly the type of dynamic behavior an agent needs to know.

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 for the complexity involved and front-loads the core identity in the first clause. A few details are repeated or wordy, such as emphasizing identical/experimental twice, but every sentence contributes meaningful state or usage information.

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

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

Given the dynamic experimental nature and lack of an output schema, the description adequately covers current behavior, version relationship, and invocation guidance by pointing to ask_pipeworx's exact argument and response shape. It is complete enough for an agent to select and call the tool correctly, though it does not independently define the response shape.

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 every alias is already described. The description adds no parameter-specific detail beyond 'same arguments' and 'use it exactly like ask_pipeworx,' so the baseline of 3 is appropriate since the schema carries the semantic burden.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx, an identical universal router over 5,708 tools, and explicitly contrasts it with the stable router via 'candidate routing improvements.' This makes its role and differentiation from ask_pipeworx 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?

It gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing,' and explains the experimental/compare-to-stable context. It does not explicitly state when not to use it or mention grounded/other alternatives, but the conditional state ('No candidate is active right now') provides clear usage context.

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

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

Annotations already mark this as read-only and idempotent, so the bar for additional disclosure is lower. The description goes well beyond that: it explains the extraction is limited to tool results, enumerates refusal reasons, and discloses the extra LLM call cost. This is rich behavioral context that annotations do not convey.

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

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

The description is long but every sentence earns its place: purpose, mechanism, return format, refusal reasons, usage guidance, and cost tradeoff. Important information is front-loaded ('Hallucination-resistant answer mode') and the structured refund/refusal details are easy to scan.

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

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

For a complex tool with no output schema, the description fully compensates by specifying the success payload shape, the refusal payload shape, all refusal reason enum values, and the operational cost. An agent has everything needed to decide when to call it and interpret its result.

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

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

Schema description coverage is 100%, with every parameter and alias clearly documented as accepting a natural-language question. The description adds no parameter-specific detail beyond that, which is appropriate given the schema already covers it. Baseline 3 applies.

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

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

The description states a specific purpose: grounded, hallucination-resistant answering for high-stakes reads, and explicitly distinguishes itself from ask_pipeworx by the extraction/refusal behavior. The phrase 'same routing as ask_pipeworx' plus the added grounded answer mode makes sibling differentiation immediate and concrete.

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

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

It gives explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on'), names the preferred alternative for casual lookups (ask_pipeworx), and explains the tradeoff (one extra LLM call). This is exactly the kind of routing guidance an agent needs.

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

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

Adds extensive behavioral detail beyond annotations: market resolution, classification, parallel fan-out, response shapes, resolver contract, parent event extraction, news fallbacks, safety checks, closed market handling, wide spread handling, and resolution rule risk. 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?

Very long and detailed, but well-structured with clear sections. While every sentence adds value, the length may hinder quick scanning. Could be more concise without losing 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?

Covers all relevant aspects: input types, process steps, classifier list, fan-out examples, response fields, resolver logic, parent events, news error handling, safety, closed markets, liquidity warnings, and cancellation rules. No output schema, but response shapes are thoroughly described.

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%. Description adds extra meaning for 'market' (slug, URL, question text), explains 'depth' effects through examples, and details 'include_raw' behavior. Exceeds baseline 3 by providing concrete usage 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?

Clearly states it researches Polymarket bets by pulling Pipeworx data. Verbs are specific ('research', 'pull'), the resource is clear ('Polymarket bet'), and it distinguishes itself from sibling tools like polymarket_edges or polymarket_arbitrage by its comprehensive scope.

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

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

Explicitly provides use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. Does not mention when not to use or explicitly contrast with siblings, but the usage guidance 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?

Adds significant behavioral context beyond annotations: specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), confirms off-calendar fiscal year handling, mentions sorting by primary metric, and describes output including citation URIs. Annotations already indicate readOnly, idempotent, openWorld, and non-destructive, and description fully aligns and enriches with these details.

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

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

The description is front-loaded with trigger phrases and a strong usage directive. While it is lengthy, every sentence adds necessary information (data sources, sorting, output format). Slightly long but efficient given the complexity of the tool.

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

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

For a tool with no output schema, the description adequately covers return format ('paired data + pipeworx:// citation URIs') and key behaviors. It addresses the two entity types, data sources, sorting, and off-calendar handling. Minor gap: precise output structure not detailed, but sufficient for 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?

With 100% schema coverage, the description still adds substantial meaning: for 'type', it explains what data is pulled for each enum value; for 'values', it gives ticker/CIK examples for companies, drug name examples, and restrains min/max items. This goes well 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 uses specific verbs ('compare', 'rank') and resources ('entities', 'companies', 'drugs'), clearly stating it performs side-by-side comparison of 2-5 items. It lists many natural language triggers and distinguishes itself from 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 states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing direct guidance on when to use this tool over alternatives. Also gives examples like 'which is bigger / better / larger / more profitable' that clarify usage context.

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

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

Despite the annotations already declaring readOnlyHint=true, openWorldHint=true, and idempotentHint=true, the description adds substantial behavioral context: auth requirements (free plan vs. paid for depth:'thorough'), latency expectations (15-60s, up to ~90s), the guaranteed fetchability of citations, the never-invented gaps[] behavior, semantic excerpting of large records, and contradiction detection in standard/thorough modes. No contradictions with annotations exist.

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

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

The description is dense and long but front-loads the most critical constraints (account requirement and alternative routing) before diving into mechanics. Some redundancy exists—paid plan mention and 'use ask_pipeworx' appear multiple times—but the length is largely justified 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 fully compensates for the lack of an output schema by explaining the findings packet structure (evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field). It also covers auth, pricing, latency, limitations for current-news topics, and sign-in fallbacks. Given the tool's complexity, nothing essential for an agent to invoke it correctly is omitted.

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

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

Schema coverage is 100% with both parameters already well-documented. The description adds meaningful extra semantics beyond the schema, such as depth:'thorough' requiring a paid plan, the hop/facet behavior per depth mode, and confirmation that question is natural language suited to broad/multi-part queries. This goes beyond the baseline of 3, though the schema already carries most parameter 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 the tool performs grounded multi-source research across Pipeworx's structured data sources and decomposes questions into facets routed to 5,708 tools in parallel. It explicitly contrasts with open-web search and names the exact use case (broad/multi-part questions), making it easy to distinguish from siblings like ask_pipeworx.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and direct when-not-to-use instructions: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead.' It names specific sibling alternatives and the conditions that select them.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, minimizing safety concerns. The description adds behavioral context: returns top-N relevant tools with full schemas and examples, ready to call directly.

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?

Relatively concise given the amount of information; front-loaded with purpose. Could trim some redundancy but still effective.

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

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

Fully describes what the tool returns (top-N tools with names, descriptions, input schemas, examples) and how to use it. No output schema needed; the description compensates completely.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining query accepts aliases (q, task, search, description) and provides natural language examples, enhancing usability.

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

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

The description clearly states the tool finds tools by describing a data/task, lists specific domains (SEC filings, FDA, etc.), and distinguishes itself from sibling tools which are specific function tools.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context and examples of use.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so safety is clear. Description adds crucial behavioral context: parallel fan-out across multiple sources, patent API sunset soft-fail, and specific return structure. No contradictions.

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

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

Description is reasonably concise given the complexity, front-loaded with example queries. Every sentence adds value, though could be slightly streamlined (e.g., patent soft-fail detail could be condensed).

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 description correctly explains return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). Covers parallel call behavior, soft-fail, and source limitations. Adequate for a tool with multiple data sources.

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. Description reinforces that type is only 'company' and value is ticker or CIK (not names), adding examples. Baseline 3 for full schema coverage; extra nuance (zero-padded CIK, names not supported) raises to 4.

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

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

The description clearly states it provides a full cross-source profile of a US public company, listing specific data sources and return fields. Examples like 'Tell me about X' and 'brief me on Tesla' clarify intent. It distinguishes from siblings like get_company_news (single source) and compare_entities.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also specifies when not to use: 'Names not supported (use resolve_entity first if you only have a name).'

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 confirms destructive behavior matching annotations. Adds context about clearing sensitive data, but no additional 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?

Two sentences with no redundancy; front-loaded with action and purpose.

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

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

Complete for a simple tool with one parameter, no output schema, and clear annotations. Usage guidance and sibling references fill 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 covers parameter fully (100% coverage). Description adds no new technical detail but hints at key origin via pairing with remember/recall.

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?

Clear verb 'Delete' and resource 'previously stored memory by key'. Distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use (stale context, task done, clear sensitive data) and pairs with related tools.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it fetches the page, extracts title/description/key links, and emits standard markdown, which aligns with annotations and gives operational context. No contradictions.

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

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

Description is a single paragraph of three sentences, all essential: what it does, how it works, and use cases. No redundancy or fluff.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers purpose, process, output format, and use cases completely. Annotations reinforce safety. No missing information.

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

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

Schema has 100% coverage for 2 parameters. Description adds value by providing examples (e.g., full URL format) and noting default/max for max_links, which aids correct usage beyond schema alone.

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

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

Description clearly states it generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt), and purpose (AI crawler indexing). It distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation.

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

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

Description explicitly lists use cases: getting client site indexed, drafting own project, auditing competitor AI view. While it doesn't mention when not to use or alternatives explicitly, the contexts are clear enough for an 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 indicate read-only, idempotent, and non-destructive behavior. The description adds that the tool returns headline, summary, source, and URL, but does not disclose potential rate limits, API key requirements beyond the schema, or pagination behavior. This is adequate but not exceptional given 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 short (two sentences plus an inline example), with no wasted words. Information is front-loaded with the purpose, followed by return fields and an illustrative example, making it efficient for an AI agent to parse.

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

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

With an output schema present, the description is mostly complete: it names the key return fields (headline, summary, source, URL). It does not discuss error handling or result limits, but given the output schema, the agent can infer return structure. The example adds practical context.

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

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

The input schema already has 100% coverage with descriptions for all four parameters (symbol, from, to, _apiKey). The description's example mirrors the schema's examples, adding minimal new meaning. This meets the baseline but does not enhance understanding beyond what the schema provides.

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

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

The description explicitly states the tool gets recent news articles for a company within a date range, listing the returned fields (headline, summary, source, URL). This clearly differentiates it from sibling tools like get_quote or search_symbol, which serve different 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?

The description provides a concrete example but does not offer guidance on when to use this tool versus alternatives. There is no mention of when not to use it or prerequisites, leaving the agent to infer usage from the purpose alone.

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 behavioral context about the range of results (upcoming/recent) and the effect of the symbol parameter. 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 two concise sentences plus an example, front-loaded with the core purpose. No fluff.

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

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

Given the simple parameter set, annotations covering safety, and an output schema, the description sufficiently explains the tool's behavior. It covers both usage modes (single company vs market) and optional date filtering.

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

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

The schema has 100% parameter description coverage, so baseline is 3. The description reinforces the symbol parameter behavior and provides an example call, but does not add substantial new meaning beyond the schema.

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

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

The description clearly states 'Get upcoming and recent earnings reports' and explains the symbol parameter for single-company vs market-wide calendar, distinguishing it from sibling tools like get_company_news or get_quote.

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

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

The description provides clear instructions on when to pass symbol vs omit it, and mentions optional date-range filtering. It does not explicitly reference alternative tools, but the scope is evident.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that the quote is real-time and includes specific fields, but does not disclose any additional behavioral traits beyond what annotations provide.

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

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

The description is a single sentence with a relevant example, containing no extraneous words. Every part adds value.

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

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

The tool is simple with two parameters and no nested objects. Annotations fully cover safety. Output schema exists (not shown but noted). The description mentions return fields, making it complete 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%; both parameters have clear descriptions. The description provides an example but adds no meaning beyond the schema. With high coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves a real-time stock quote and lists the data fields (price, change, volume). The example reinforces usage. It distinguishes from sibling tools, none of which are quote-specific.

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

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

The description implies use for stock quotes but does not explicitly state when to use it over alternatives or when not to. Given sibling tools are unrelated, the context is clear but lacking explicit guidance.

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

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

Annotations already indicate readOnly, idempotent, not destructive. Description adds value by specifying return fields and clarifying that it lists only active subscriptions by default. No contradictions.

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

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

Two concise sentences: first states purpose and return fields, second gives usage guidance. Front-loaded and no redundant information.

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

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

For a list tool with one optional parameter and no output schema, the description adequately covers return fields and usage context. Combined with annotations and schema, it is fully informative.

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

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

Schema coverage is 100%, so baseline is 3. Description does not elaborate on the 'include_inactive' parameter beyond what schema provides, but it implicitly aligns with the default behavior.

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 verb 'List' and resource 'the caller's active subscriptions'. Explicitly distinguishes from siblings 'subscribe' and 'unsubscribe' by stating use case 'to review what you're monitoring before adding more or to find an id to cancel'.

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

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

Provides explicit guidance on when to use: 'before adding more' or 'to find an id to cancel'. Implicitly advises against using for other purposes by contrasting with related tools.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, etc., so the description adds valuable context: claim_token flow, rate limiting (5/day), free usage, and daily digest processing. It doesn't overclaim side effects, but could mention what data gets sent to the team; still well above baseline.

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

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

The description is long but every sentence earns its place: what it does, when to use, exclusions, output flow, rate limit, and cost. It is front-loaded with the core purpose and wastes no 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 having no output schema, the description covers the return behavior (claim_token), usage scenarios, exclusions, limitations, and roadmap impact. It is complete for a 4-param tool with a nested object.

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 real value beyond the schema by explaining the claim_token round-trip ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by adding message guidance ('don't paste the end-user's prompt').

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb and resource. It clearly distinguishes this feedback tool from the sibling tools (research, alerts, memory tools) by its unique role as a feedback channel.

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 (bug, feature/data_gap, praise) and when NOT to use (tools from other MCP servers), with a clear alternative (file with that server). Also clarifies ambiguity by saying 'Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already indicate read-only/idempotent; description adds data source (CF analytics-engine), no PII, and caching behavior, going beyond annotations 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?

Description is compact (5 sentences), front-loaded with purpose, and each sentence adds value without redundancy.

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

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

For a simple tool with one optional parameter and rich annotations, the description covers purpose, return types, use cases, data source, caching, and privacy – 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 covers 100% of the parameter meaning with detailed enum descriptions; description adds minimal extra context, so baseline 3 is appropriate.

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

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

Clearly states it returns top tools, packs, and call volume over a window, with explicit use cases that differentiate it from siblings like discover_tools or ask_pipeworx.

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

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

Lists three specific use cases but does not mention when not to use or give alternatives; however, the context is ample.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral context: algorithmic steps (monotonicity, partition sum), filtering rules (Jaccard similarity, placeholder filter), response structure (opportunities, partition_check, fill_check), and the condition for not trading (realizable_edge_pp ≤ 0). 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 front-loaded with core purpose and then provides substantial technical detail. While every sentence adds value, the length could be streamlined for a general audience. However, given tool complexity, it is reasonably concise.

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

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

Covers all aspects: purpose, modes, inputs, algorithmic details, filtering, response structure, trade eligibility, and links to sibling tool. Lacks output schema but describes return fields explicitly. No missing critical information.

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

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

Schema coverage is 100% for both parameters. Description adds value by clarifying that event accepts full URLs, providing example slugs, explaining default behavior with no args, and detailing differences between event and topic modes.

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

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

The description uses a specific verb-resource pair: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings by specifying the unique algorithmic approach and three usage modes (no args, event, topic).

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 each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also provides negative guidance via fill check and recommends polymarket_fill_risk for custom sizing.

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

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

Description adds substantial behavioral context beyond annotations, including caching behavior, response structure, edge calculation details (net of slippage, Kelly fractions), tradeable-edge knobs, and diagnostics. No contradiction with annotations.

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

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

Description is very long and detailed. While all information adds value, it could be more concise by moving some details (e.g., exact Kelly formulas, specific model names) to the schema or an external reference. The structure is front-loaded with purpose, but length may overwhelm.

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

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

Despite no output schema, the description fully explains the return format, including segments, per-opportunity fields, tradeable-edge knobs, and diagnostics. It also mentions caching and parameter effects, making it complete for a tool with 9 parameters.

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

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

Schema coverage is 100%, and each parameter has a good description in the schema. The tool description further explains how these parameters affect the analysis (e.g., slippage, liquidity, spread), adding value beyond the schema definitions.

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

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

Description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. This distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker which may have different focuses.

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

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

Description provides clear context for when to use the tool (finding edges based on Pipeworx data) and explains three model families and knobs. However, it does not explicitly compare to sibling tools or provide 'when not to use' guidance, which would strengthen it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable details about response structure, decay computation, data gaps, and limitations, enhancing transparency.

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

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

The description is moderately long but well-structured with distinct sections (RESPONSE, LIMITS). Every sentence adds value; could be slightly more concise but 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 the absence of an output schema, the description fully explains the response format with fields and their meanings. It also covers limitations and edge cases, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with parameter descriptions. The description adds default values, clamping for days, and explains window families, providing meaning beyond the schema.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers a specific question about edge history. It distinguishes from the sibling 'polymarket_edges' tool by focusing on time-series analysis.

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

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

The description explains parameters and defaults, and implicitly contrasts with the static edge snapshot tool. Lacks explicit 'when not to use' or alternatives, but provides 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 declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. Description adds context: REQUIRES one of market or event, explains return fields (top_of_book, slippage, etc.), and warns about risks like forced directional risk. No contradictions with annotations.

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

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

Description is thorough but well-structured with uppercase labels for mode requirements. Each sentence adds value, though slightly verbose. Front-loaded with core purpose and mode summary.

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), description is comprehensive. Covers inputs, outputs, and usage context. No output schema, so description fully explains return structure and warnings.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description adds significant meaning: explains mode-dependent behavior for side, market vs event, size_usd interpretation (spend vs target proceeds vs settlement notional), and defaults. Adds value beyond schema.

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

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

Description clearly states the tool checks realizable vs theoretical edge against live order-book depth, with two distinct modes (single-market and basket) and detailed explanations. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by indicating it should be used before them.

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

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

Explicitly tells when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also warns about consequences of not using (partial basket fills become directional position). Provides 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?

The description richly discloses behavior beyond the annotations: it explains compatibility_warning and compatibility_codes, lists all possible codes, states that legs with unknown metric_type or match_subtype are never paired, describes skipped_cross_type and skipped_cross_subtype counters, and warns that pre-mapped pairings are unverified. These are exactly the kind of caveats an agent needs on a cross-venue comparison tool.

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

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

The description is long, but nearly every sentence carries a distinct behavioral or safety detail that cannot be inferred from the schema or annotations. It is front-loaded with the core purpose and the two modes before diving into safety fields, and it closes with a relevant caveat, though the dense prose could benefit from light structural formatting.

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

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

Given there is no output schema and the tool is complex with optional parameters, the description covers the response shape, safety fields, code semantics, skipped-pair behavior, counters, temporal alignment, and the practical caveat that pre-mapped topics are not necessarily tradeable. An agent has everything needed to call the tool and interpret its result.

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 already 100%, so the baseline is 3, but the description adds real semantic value: it enumerates all ten topic shortcuts, explains that the explicit Kalshi/Polymarket parameters override the topic-mapped side, and gives format examples like KXFED-26OCT and fed-decision-in-june-825. This goes well beyond the schema's descriptions.

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

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

The description opens by naming the exact resource—the cross-venue spread between Kalshi and Polymarket for the same resolving question—and immediately distinguishes it from other market tools by the two-venue comparison. It goes on to specify two concrete invocation modes, so an agent can tell what the tool does before reading any 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 clearly explains the two modes—pre-mapped topic shortcuts versus explicit ticker/slug overrides—and warns that most pre-mapped topics are not currently tradeable. However, it does not name sibling alternatives like polymarket_arbitrage or state when an agent should prefer a different tool, leaving the comparison to alternatives implied rather than explicit.

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 and idempotent. Description adds scope ('Scoped to your identifier') and behavior when key is omitted (list all keys), providing useful 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?

Three focused sentences, first sentence conveys primary action. No wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description fully explains purpose, usage, scope, and relationships to sibling 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% with parameter description already clear. Description adds context about the parameter's purpose ('omit to list all keys') and the broader usage scenario.

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?

States specific verb 'Retrieve' and resource 'value previously saved via remember' or 'list all saved keys'. Clearly distinguishes from sibling tools like 'remember' and 'forget'.

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

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

Explicitly describes when to use (look up stored context like ticker, address, notes) and provides alternatives ('Pair with remember to save, forget to delete').

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 not destructive. The description adds details about returned fields (source, citation_uri, raw payload) and the mark_read flag's effect on subsequent calls, which is valuable 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 concise (one paragraph, ~120 words) and front-loaded with the primary purpose. Every sentence adds value, with no redundancy or filler.

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

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

Given the simplicity of the tool (5 optional params, no output schema), the description is comprehensive: it explains what is returned, how to filter, the mark_read behavior, and even mentions an alternative REST endpoint. 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%, so the schema already documents parameters. The description adds contextual meaning with examples (type 'sec_8k', mark_read behavior, default limit of 50), enhancing understanding beyond the schema.

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

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

The description clearly states the tool 'pull fired events from your subscription feed' and 'returns the most recent alerts', specifying both verb and resource. It distinguishes itself from siblings like 'list_subscriptions' by focusing on fired events.

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

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

The description explains when to use the tool (to get recent alerts) and mentions filtering options (type, since, mark_read, unread_only). It also notes that polling works and provides an alternative REST endpoint for scripts/dashboards, though it does not 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 readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds valuable behavioral context: fan-out to multiple sources, fallback from GDELT to GNews, and a soft-fail condition for USPTO. No contradictions.

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

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

The description is a single dense paragraph, front-loaded with query examples. It is concise (every sentence adds information) but could be slightly more structured (e.g., bullet points for sources) without losing conciseness.

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

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

Given the tool's complexity (multiple data sources, fallback logic, parameter formats) and the absence of an output schema, the description adequately covers return structure (grouped changes, count, URIs). It provides enough context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds examples (e.g., '7d', 'AAPL', '0000320193') and explains the 'since' format more concretely, but does not significantly extend beyond what the schema already provides.

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

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

The description uses specific verbs ('change feed', 'fans out') and clearly identifies the resource (company recent changes across multiple sources). It distinguishes itself from sibling 'entity_profile' by contrasting dynamic change feed vs 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?

The description provides explicit query examples and a clear alternative: 'Use entity_profile instead when you want the static profile'. It implies usage scope (monitoring changes over a window) and fallback behavior, but doesn't explicitly state when NOT to use it (e.g., for real-time data).

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 idempotent and non-destructive write operation. Description adds key behavioral details: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. 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?

Four sentences, tightly packed with purpose, usage guidelines, and behavioral facts. No superfluous words. Front-loaded with main purpose immediately.

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

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

For a simple two-parameter key-value store with no output schema, the description covers all essential aspects: what it stores, scoping, persistence, and pairing with complementary 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?

Input schema already describes 'key' and 'value' with examples (key: 'subject_property') and value types (any text). Description further provides concrete use-case examples (findings, addresses, preferences), adding meaningful context beyond schema.

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

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

The description clearly states 'Save data the agent will need to reuse later' with specific examples of what to store (resolved ticker, target address, etc.). It distinguishes itself from siblings 'remember', 'recall', and 'forget' by explicitly pairing with them.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides clear guidance on pairing with 'recall' and 'forget', and differentiates behavior for authenticated vs anonymous sessions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds valuable behavioral details: identifiers that cannot be resolved are explicitly listed under 'unresolved' rather than omitted, LEI/FIGI enrichment degrades gracefully if upstream services are unavailable, and each call cascades through several endpoints. This is rich, non-obvious 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 lengthy but well-structured with clear sections (intro, supported types, degradation notes). It front-loads the most important usage guidance ('Use FIRST') and every sentence carries substantive information. It could be trimmed slightly without losing value, but the structure aids comprehension.

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

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

Given the tool's complexity (two entity types, no output schema), the description does an excellent job covering return behavior: it mentions source-labeled identifiers, the 'unresolved' field, drug citations, and graceful degradation. This provides sufficient context for an agent to know what to expect and how to handle failures.

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

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

Schema coverage is 100%, but the description adds meaningful semantics beyond the schema: it explains that ISIN inputs map to legal entities via GLEIF, that drugs return RxCUI plus ingredient and brand, and that input can be ticker, CIK, ISIN, or name for companies. This enriches understanding of parameter behavior.

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

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

The description clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It uses a specific verb ('resolve'), resource ('entity names to identifiers'), and distinguishes itself from siblings by explicitly saying 'Use FIRST' and noting it replaces manual 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?

The description provides clear context for when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also gives examples of typical queries. However, it does not explicitly mention alternatives or when not to use it, so it stops short of a 5.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, which are consistent. Description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density per entity, providing useful behavioral context beyond the annotations.

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

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

Two concise sentences plus an example quote. Front-loaded with key verb and resource. No wasted words; every sentence adds valuable 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 4 parameters (1 required) and no output schema, the description explains the tool's purpose, how it works (probing each entity), and what is returned (ranked list with score, confidence, signal density). Covers enough for an agent to use it effectively, though exact output format could be clearer.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description mentions 'probes each entity' but does not add new semantics beyond what is in the schema. Baseline 3 is appropriate.

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

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

Description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check, ranking, and surfacing most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the competitive AI audit context.

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 'Useful for competitive AI-marketing audits' and provides an example question. Lacks explicit when-not-to-use or listing alternatives, but the context signal is clear enough for an AI agent to decide.

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 true and destructiveHint false. The description adds context: it fans out to two external services, bundlephobia's first measurement can take 5-30s and may time out (noted in sources_failed), and partial failures yield graceful degradation. No contradictions with annotations.

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

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

The description is a single paragraph with multiple sentences, but every sentence adds distinct information. It front-loads the main purpose and includes necessary details like fallback behavior and graceful degradation. Slightly longer than ideal but not wasteful; still well-structured for comprehension.

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

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

Given no output schema, the description thoroughly explains the return value: a summary block with specific fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and a list of recent alternative versions. It also covers partial failures with sources_failed. This is complete for an agent to understand what to expect.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no additional semantic depth beyond what the schema already provides for 'package' (npm package name with scoped packages accepted) and 'version' (defaults to latest). The description simply restates the schema behavior.

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

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

The description clearly states the tool performs a composite check for npm packages combining data from deps.dev and bundlephobia, covering license, advisories, version history, bundle size, dependency count, and ESM/tree-shake support. This specific verb-resource combination distinguishes it from all listed siblings, which focus on finance, politics, or general queries.

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

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

The description explicitly tells when to use the tool: whenever an agent asks about package safety, popularity, size, or cost (e.g., 'is X safe / popular / small' or 'what does adding lodash cost me'). It also notes limitations: NPM ecosystem only in v1, with fallback to deps.dev:version for other ecosystems, and mentions graceful degradation for bundlephobia timeouts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds an example but no further behavioral context beyond what annotations provide.

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

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

Two clear sentences plus a concise example. No wasted words; information is front-loaded and efficient.

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

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

For a simple search tool with 2 parameters and an output schema presumed present, the description adequately explains functionality and usage. No gaps observed.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds an example but no new semantic meaning beyond the schema.

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

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

The description clearly states the tool searches for stock ticker symbols by company name or keyword, using a specific verb and resource. It is distinct from siblings like get_company_news or get_quote.

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 indicates when to use (search for symbols), but does not explicitly exclude alternatives or provide when-not-to-use guidance. However, the purpose is clear enough given 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?

The description adds significant behavioral context beyond the annotations, such as embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and character cap (200K with truncation flag). No contradictions with annotations.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose and then provides supporting details. It is concise and each sentence adds value, though it could be slightly more compact.

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

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

Given the tool's complexity and lack of output schema, the description adequately covers inputs, behavior, and return values (passages with offsets and scores). It explains the embedding technique and truncation, making it sufficiently 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 description coverage is 100%, so the baseline is 3. The description adds value by clarifying the purpose of each parameter, especially the query examples and the char limit for text. It reinforces but does not significantly extend 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 verb (search inside), the resource (a fetched record), and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and providing concrete examples like SEC 10-K. The purpose is unambiguous and specific.

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 this tool: when a record is too large for the prompt, and explains the benefits (saves context, returns relevant passages with offsets). It also mentions pairing with another tool, but does not provide explicit when-not-to-use guidance or exclusions.

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

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

Annotations already provide readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: returns subscription id, delivery constraints (SMS 10/day cap, webhook auto-disable after 10 failures, signing secret one-time return). It does not contradict annotations, though the idempotentHint=true is not confirmed by the description (it says 'Create', which could imply non-idempotent if duplicate prevention isn't explicit).

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 fairly long but efficiently packed with information. The first sentence is a clear purpose statement. Every subsequent sentence adds necessary details without redundancy. Minor trim could be possible, but overall 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 the tool's complexity (3 parameters, 2 required, nested objects, no output schema), the description provides comprehensive coverage: supported types, parameter formats, delivery options with constraints, return value (id), and even a note on webhook auto-disable. It fully prepares the agent for correct usage.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema: concrete examples for each type in params (e.g., sec_8k with items codes, polymarket_edge with topic), detailed delivery channel behaviors (SMS verification requirement, webhook signing and auto-disable). This extra context is essential for correct invocation.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource combination that distinguishes 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 explicitly mentions prerequisites ('Requires a Pipeworx OAuth account; anonymous + BYO cannot persist subscriptions') and provides supported types with examples. It does not list alternatives but the context is clear enough for an agent to decide when to use this 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 indicate read-only, idempotent, and non-destructive behavior. The description adds that it returns example questions with tool shapes from the live catalog, which is useful context beyond the annotations.

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

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

The description is verbose but front-loaded with common queries and all sentences add value. It could be slightly trimmed without losing clarity, but it effectively serves its purpose.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description provides complete context: what it returns, when to use it, and how to invoke it. It also mentions reliance on the live catalog for freshness.

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

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

The schema covers the optional topic parameter with enumerated values. The description enriches this by providing examples (e.g., 'finance', 'pharma') and explaining behavior when omitted ('Omit for a cross-category spread').

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings like ask_pipeworx and discover_tools by positioning itself as the first tool to use when unfamiliar with Pipeworx.

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

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

The description explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to call with no arguments vs. with a topic, providing clear invocation context.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds valuable context: deactivation vs deletion, preservation of history, and ownership enforcement, surpassing annotation coverage.

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

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

Two sentences, front-loaded with action and constraint, each sentence earns its place with no redundancy.

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

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

For a simple tool with 1 parameter, no output schema, description fully addresses action, ownership constraint, and lifecycle behavior. Complete for its complexity.

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

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

Schema covers parameter 'id' with description fully. Description merely restates 'by id' without adding new meaning; baseline 3 due to high schema coverage.

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

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

Description uses specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing 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 explicitly, guiding when to use. Could improve by mentioning when not to use (e.g., cannot cancel others' subscriptions), 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 far beyond annotations by disclosing the dual-path routing, the meaning of each verdict (including the crucial distinction between could_not_verify and unsupported), and the caller instruction not to treat could_not_verify as evidence. It also explains the structured vs grounded pipeline behavior, adding substantial context about what the tool actually does internally.

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

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

The description is dense but well-organized, starting with the core purpose then expanding into pipelines, outputs, and warnings. Every sentence adds value, especially the 'IMPORTANT for callers' warning and the 'Replaces 4–6 sequential calls' note. It's longer than average, but the complexity of the tool justifies the length.

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

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

The description covers the full behavior: what the tool does, when to use it, the two distinct execution paths, the complete verdict vocabulary, the meaning of each outcome, and a critical error-handling caveat. Despite no output schema, the description sufficiently explains return values and edge cases, making it 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 coverage is 100%, so both parameters are well-documented. The description reinforces the claim parameter with natural-language examples and adds nuance about tolerance in the schema (not the description). While the description doesn't directly elaborate on parameters beyond schema, it does mention the percent-delta math and tolerance cap indirectly. Baseline 3 is appropriate.

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

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

The description clearly states the tool verifies natural-language factual claims and returns a verdict, using specific verbs like 'fact check' and 'verify'. It distinguishes itself from sibling tools by emphasizing the verdict-driven, single-call nature and the two specialized pipelines (SEC/XBRL vs grounded), making its purpose unambiguous.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims and other claims, giving clear routing guidance. While it doesn't name alternative tools to avoid, the 'Replaces 4–6 sequential calls' positioning conveys when it's preferable over a multi-step approach.

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