Devto

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

The description adds significant behavioral context beyond annotations: default model (Workers AI Llama), optional Anthropic key with cost implication, return structure (per-model {score, confidence, signals, raw_response} + combined view). Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description does not contradict.

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

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

The description is four sentences, each adding value without redundancy. It front-loads the primary action and return format, then includes usage guidance and example use cases. No fluff or unnecessary details.

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

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

Given the tool's moderate complexity (4 parameters, no output schema, good annotations), the description explains the purpose, usage, and return structure (score, confidence, signals, raw_response). It could be more specific about the raw_response field or how confidence is calculated, but it is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description reiterates parameter roles (entity, models, _apiKey, context) but does not add new meaning beyond what the schema already provides. It does provide usage context (default model, API key purpose) but that is already in the schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score (0-100) per model. It uses specific verbs ('probe', 'score') and resource ('business/brand/product/topic'), and distinguishes from sibling tools like 'ask_pipeworx' (general Q&A) and 'deep_research' by focusing on AI visibility audits.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not provide explicit when-not-to-use guidance or direct comparisons to alternatives, though the context makes it clear this is a specialized audit 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?

Beyond the annotations (readOnlyHint, openWorldHint), the description adds useful behavioral context: routes across 5,529 tools, fills arguments, returns stable citation URIs, and works on every tier. This goes beyond simple read-only status, though it stops short of disclosing error or edge-case behavior.

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

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

The description is long but well-structured, opening with a strong directive and then providing context, examples, and alternatives. Every sentence adds value, though it is wordier than strictly necessary for a default tool.

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

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

For a broad, complex tool with no output schema, the description is remarkably complete. It covers scope, use cases, example queries, alternative tools, and return behavior (citations), leaving little ambiguity for an agent.

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

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

Schema coverage is 100% and the schema already documents the main parameter and all aliases. The description adds examples of valid questions but does not clarify parameter constraints or formatting beyond what the schema provides, yielding the baseline score for high schema coverage.

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

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

The description clearly states the tool's purpose: answering factual questions about current or historical data with structured answers and citations. It explicitly differentiates from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for specific cases.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', lists trigger phrases ('what is', 'look up', etc.), provides examples, and explicitly states 'START HERE for most questions' while naming alternatives for when more depth is needed.

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

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

The description discloses the beta nature, the possibility of live routing changes, and that no candidate is currently active. It adds the important reassurance that it 'Falls back to nothing — this IS a full working router', clarifying it does not degrade to a stub. Annotations already cover read-only, idempotent, non-destructive behavior, so the description complements rather than repeats, adding experimental-context value. It does not mention rate limits or error modes, but that is acceptable given the 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?

The description is three sentences long and front-loaded with the essential identity ('Beta version of ask_pipeworx'). Each sentence adds meaningful context: similarity to the stable version, current experimental state, and usage instruction. While not ultra-brief, it avoids fluff and packs relevant information efficiently for a tool with this nuance.

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 that this is a variant of an existing tool, the description covers the relationship to ask_pipeworx, the experimental nature, current status, and usage guidance. It doesn't explain what a universal router does in detail, but that is likely established by the sibling tool. With no output schema, it mentions 'same response shape' to convey return expectations. This is sufficiently complete for an AI agent differentiating between the beta and stable versions.

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 fully documents all six parameters (question plus five aliases) with descriptions, achieving 100% schema coverage. The description does not add new parameter details beyond saying 'same arguments' as ask_pipeworx, which is useful but not deeply informative. Since schema coverage is complete and no enums or nested objects exist, a baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same tool set and argument structure. It distinguishes itself from the stable ask_pipeworx by explaining it may have routing improvements under test, though it currently matches ask_pipeworx exactly. The phrasing is slightly convoluted but does state the core function (routing questions to 5,529 tools) and its relationship to the sibling.

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

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

The description explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. This gives clear when-to-use guidance and implicitly names the stable ask_pipeworx as the alternative. It also clarifies current state (no active candidate), removing ambiguity about whether behavior differs right now.

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 readOnly and non-destructive hints, but the description adds valuable behavioral context beyond those: it discloses the extra LLM call cost, the strict rule of using 'ONLY what the tool result contains,' and the explicit structured refusal reasons (not_in_source, no_tool_match, etc.). 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 dense but well-structured: a clear opening purpose, then mechanism, return format, usage, and cost trade-off. It is longer than the high-example but every sentence earns its place. Slightly verbose, so a 4 rather than 5.

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

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

With no output schema, the description fully explains both success and refusal return structures, including field names and refusal reasons. It also covers when to use, cost implications, and the exact nature of the tool's constraint. This is highly complete for a complex tool.

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

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

Schema description coverage is 100% (all params are aliases for 'question'), so the schema already fully documents the parameter. The description adds no parameter-specific guidance beyond what the schema says, staying at the baseline of 3.

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

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

The description opens with a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes from sibling ask_pipeworx by describing the extraction-from-result behavior and refusal reasons, making the tool's unique role explicit.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and when to avoid: 'prefer ask_pipeworx for casual lookups.' It also names the alternative tool and provides a trade-off (cost), satisfying the when/when-not/alternatives requirement.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds extensive behavioral details: resolution contract logic (market_match_confidence, alternatives), parent_event extraction, news fallback mechanisms, safety short-circuits for low-confidence/dead markets, wide-spread illiquidity notes, and cancellation rule parsing. This far exceeds the minimal transparency needed.

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

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

The description is comprehensive and front-loaded with the core action, but it's lengthy (multiple paragraphs with many details). Every sentence is informative and earns its place, making it a 4 rather than a 5 (which would require conciseness with no waste).

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, no output schema, numerous edge cases), the description is exceptionally complete. It covers resolution confidence, parent events, illiquidity, cancellation rules, news fallback errors, and status codes for dead/low-confidence markets. No relevant gaps remain.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema: it provides concrete examples for the 'market' parameter (slug, URL, question text), explains 'depth' (quick vs thorough with source count), and specifies when to use 'include_raw' (summarized vs full payloads). This context helps agents choose parameter values effectively.

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

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

The description opens with a specific verb-resource combination ('Research a Polymarket bet') and clearly distinguishes from siblings like polymarket_edges and polymarket_arbitrage by detailing its scope (pulling Pipeworx data, resolving markets, fanning out to category-specific data packs).

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 lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), providing clear context. It does not explicitly state when not to use the tool or name alternatives, but the sibling tool list and implied scope make exclusions unnecessary for a score of 4.

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

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

Annotations already declare readOnly, idempotent, non-destructive; description adds specifics: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting, and citation URIs.

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

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

Description is well-structured but slightly verbose; however, every sentence adds value, making it efficient for an agent.

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

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

Comprehensively covers both entity types, data sources, output (paired data, citation URIs), and replaces many lookups; no gaps given no output schema.

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

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

Schema coverage is 100%; description enriches by explaining data sources per type and providing examples (tickers, drug names), which adds meaning 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 the tool does side-by-side comparison of 2-5 entities (companies or drugs) with concrete query examples, distinguishing it from siblings like entity_profile.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing strong guidance on when to 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?

The description goes well beyond the annotations by disclosing account/plan requirements, latency expectations (15-60s, up to ~90s for thorough), gap[] handling (never invents answers), parallel routing across 5,529 tools, semantic excerpting, contradictions[] for standard/thorough, and the guaranteed-fetchable citation_uri claim. It is consistent with the read-only and idempotent annotations.

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

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

The description is long but dense with useful information and front-loaded with the mandatory account requirement and core purpose. The repeated ask_pipeworx recommendations appear in different contexts, but each sentence serves a purpose; it could be trimmed slightly without losing essence.

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?

This is a complex tool with no output schema, and the description covers all critical aspects: input usage, output contract (findings packet with fields), failure behavior (gaps[]), timing, prerequisites, and alternatives. It fully prepares an agent to decide when and how to invoke the tool.

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

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

The input schema already thoroughly documents both parameters (question and depth with per-enum descriptions), giving a baseline of 3. The description adds practical guidance beyond the schema: runtime expectations, plan requirements for 'thorough', example questions, and clarification of how depth affects gap recovery and contradiction scans.

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 over structured data, decomposes the question into facets, and returns a findings packet with evidence, confidence, and citations. It explicitly contrasts with ask_pipeworx for single lookups, making its purpose and scope 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 when-to-use guidance: use ask_pipeworx instead if not signed in, for single lookups, or for breaking/current-news topics; use deep_research for broad/multi-part structured-data questions. It also explains the limitations (empty gaps[] for topics outside the structured catalog) and alternative tools.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: that results are 'ready to call directly, no second schema lookup needed,' and that it provides an option set rather than a single answer, complementing 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?

The description is a single block of four sentences that front-loads purpose and usage. It includes necessary details (domain examples, return format) with no redundancy or fluff, achieving high efficiency.

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 discovery role, the description fully covers what it does, when to use it, what it returns (schemas, examples), and its behavior (no second lookup). Without an output schema, the description adequately explains return value.

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

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

Although schema coverage is 100% with descriptions for all 6 parameters, the description does not significantly expand on their meaning beyond the schema. It notes aliases (task, q, description, search) which are already documented. Score reflects adequate but not extra value.

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

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

The description clearly states the tool's purpose as 'Find tools by describing the data or task.' It indicates discovery, browsing, and searching for tools across specified domains, and highlights that it returns 'top-N most relevant tools with names, descriptions, and full input schemas,' distinguishing it from sibling tools.

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

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

The description explicitly tells when to use the tool: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists specific use cases (SEC filings, financials, etc.), providing clear guidance on 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?

Description details what data is returned (CIK, filings, fundamentals, patents, news, LEI) and mentions the USPTO API sunset and soft-fail behavior. Annotations already indicate read-only and idempotent, so the description adds valuable behavioral context beyond that.

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

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

Description is detailed but efficient, using bullet-like structure and front-loading examples. Could be slightly more concise, but the information density is appropriate for a complex 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?

With no output schema, the description fully explains the return fields (cik, filings, fundamentals, patents, news, LEI) and limitations (USPTO sunset, name handling). Completeness is high given 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%, and description goes beyond by specifying that names are not accepted and that value can be ticker or zero-padded CIK, which is critical for correct usage.

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 defines the tool's purpose: providing a holistic profile of US public companies from multiple sources. Example queries illustrate usage, and it distinguishes from sibling tools like resolve_entity by stating names are not supported.

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 that this tool should be preferred over chaining individual lookups for holistic views. Provides clear guidance on when to use resolve_entity first if only a name is available, and notes that ticker or CIK are required.

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 destructiveHint:true and idempotentHint:true. The description adds that deletion is for clearing stored data, but does not mention behavior on missing keys or confirm irreversibility beyond 'delete'.

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, no wasted words. First sentence states purpose, second gives usage context. 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 tool with one required parameter and no output schema, the description covers purpose, usage context, and pairing with siblings. Complete enough for effective selection and invocation.

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

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

Schema coverage is 100% for the single parameter 'key', which already has a description. The description does not add additional meaning beyond 'by key'.

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 'Delete a previously stored memory by key.' It uses a specific verb ('delete') and resource ('previously stored memory'), and clearly 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?

The description provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with siblings, which helps the agent decide between 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?

Description explains the process: fetches page, extracts title/description/key links, emits markdown. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds process details 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?

One concise paragraph, front-loads the main action, no wasted words. Could be slightly more structured but overall efficient.

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

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

With only 2 parameters and no output schema, the description provides sufficient context: explains output format, use cases, and process. Annotations cover safety and idempotency, so nothing critical is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by noting the default and max for max_links, and clarifies that output is a single text blob. This enhances understanding 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?

Clearly states the tool generates a production-ready llms.txt file for any URL, specifies the output format and use cases, and distinguishes from sibling tools like scan_competitor_ai_presence by focusing on llms.txt 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?

Explicitly lists three use cases (getting a client's site indexed, drafting for own project, auditing competitor). Does not include when-not-to-use or alternatives, but the context is clear enough.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds return fields (title, author, etc.) and source (DEV.to), 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?

Two sentences, front-loaded with purpose, no redundant phrases. Every word earns its place.

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

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

Simple tool with rich annotations and output schema. Description covers purpose, input, and output appropriately, though it could mention missing details like authentication or error responses.

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

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

Schema coverage is 100% with a clear description. Description reinforces with example ('12345') and clarifies the ID is numeric, adding marginal value over 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?

Clear verb ('Fetch'), resource ('full article content'), and identifier ('by ID'). Differentiates from siblings like get_articles (list) and search_articles (search).

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

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

Implies use when article ID is known, but lacks explicit when-not-to-use or alternative tools. Context from sibling names helps, but no direct guidance.

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

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

Annotations already declare readOnlyHint and destructiveHint, so description doesn't need to restate safety. Adds value by specifying return fields (title, author, reaction count, etc.) and that results are trending/recent.

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, no unnecessary words. Front-loaded with key information: purpose, optional filter, and return fields.

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?

Low complexity tool with output schema present, so return value details not needed. However, lacks clarification of what happens with no parameters (e.g., returns default trending or recent). Minor gap.

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 with parameter descriptions. Description only mentions tag filtering and limit default/max, which is already in schema. No major additional meaning 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?

Clear verb ('Get') and resource ('trending or recent DEV.to articles') with optional tag filtering. Distinguishes from siblings like 'get_article' (single article) and 'search_articles'.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., 'search_articles' or 'get_article'). Only implied that tag filtering is optional.

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. The description adds the specific fields returned, which is beyond what annotations provide. No contradiction.

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

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

Two sentences convey purpose, output, and usage guidance without any wasted words or repetition.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description adequately covers purpose, output fields, and usage context.

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

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

Schema coverage is 100% and the parameter description is clear. The description does not add additional meaning beyond the schema, which is sufficient.

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 lists the caller's active subscriptions and matches the title. Distinguishes from sibling tools like subscribe/unsubscribe by implying it is used for review.

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 guidance on when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' Implicitly suggests not using it when you already have the information, but could be more explicit about alternatives.

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

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

The description discloses behavioral details well beyond the annotations: rate-limiting ('Rate-limited to 5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), follow-up mechanics (claim_token flow), and the team's daily digest process. All annotations are false, so the description carries the full burden, and it does so thoroughly.

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?

While lengthy, every sentence adds essential information. The structure is logical: primary purpose, feedback categories, exclusion criteria, token flow, rate limits, and free status. It is front-loaded with the core purpose and uses concise phrasing without redundancy.

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

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

Given the tool's complexity (multiple feedback types, optional nested context, claim_token for follow-up), the description covers all necessary aspects: usage context, behavioral constraints, and the token retrieval process. No output schema exists, but the description sufficiently explains what to expect (claim_token and status updates).

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 rich parameter descriptions, so baseline is 3. The description adds extra value by advising not to paste the end-user's prompt, explaining the claim_token round-trip usage, and clarifying the context field's purpose (which tool, pack, or vertical). This elevates the score above baseline.

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

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

The description explicitly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates feedback categories (bug, feature, data_gap, praise) and distinguishes itself from siblings by specifying that it reports on Pipeworx tools only, not tools from other MCP servers.

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

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

The description provides explicit when-to-use guidance: bug reports for wrong/stale data, feature/data_gap for missing capabilities, praise for what works. It also gives clear when-not-to-use instructions: 'if the tool came from a different MCP server... file it with that server instead.' The fallback for uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists') is particularly 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 context beyond annotations: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). Annotations already declare read-only and idempotent; description reinforces non-destructive nature.

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

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

Well-structured with bullet points and line breaks. Some redundancy (e.g., 'Self-aggregating signal' might be implied). Overall efficient but could be slightly shorter without losing meaning.

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

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

For a simple one-param tool with no output schema, the description fully explains what it returns and why it's useful. No gaps given the low 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?

Only parameter 'window' has enum and description. Schema coverage is 100%. Description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

Description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window'. It distinguishes itself from siblings like 'discover_tools' by focusing on trending/call volume data.

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

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

Explicitly lists three specific use cases (discovering hot data sources, confirming canonical tools, checking alignment). Does not mention when not to use or alternatives, but guidance is clear and actionable.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral detail: algorithmic approach (monotonicity, partition-sum), semantic anchor with Jaccard similarity, partition filter for placeholder slugs, fill check against live CLOB depth, and conditions under which signals are null. No contradictions with annotations.

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

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

The description is lengthy but well-structured: starts with purpose, then explains each mode with details, followed by technical nuances (semantic anchor, partition filter, fill check). Every sentence adds value, though some technical repetition could be trimmed. Front-loaded with mode selection guidance.

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, algorithm details, response fields, edge cases), the description is comprehensive. It covers response structure (opportunities[], fill_check), conditions for null signals, and integration with polymarket_fill_risk for custom sizing. No output schema exists, so the description adequately fills that gap.

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 clear parameter descriptions. The description adds extra semantics: for 'event', it explains that URLs are accepted and what checks are performed; for 'topic', it explains the cross-event scanning logic. This goes beyond the schema by explaining the behavior and recommended use.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes between modes (no args, event, topic) and explicitly distinguishes from siblings like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'pass event for a specific market', 'topic for a themed cross-event scan'. It explains the benefits of each mode and recommends event for specific markets. It does not explicitly say when not to use the tool, but the guidance is clear and actionable.

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

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

Beyond annotations (read-only, idempotent), the description details caching (1h KV cache), model families (crypto_price, news_momentum, etc.), response structure (by_segment, diagnostics), and caveats (Fed note, filter_skips). This is excellent behavioral disclosure.

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 verbose (over 400 words), which may be overwhelming for an AI agent. However, it is well-structured with clear sections for model families, parameters, and response format, partially offsetting the verbosity.

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 thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and edge cases (e.g., Fed data limitations, placeholder filters). With 9 optional parameters and high complexity, this is a complete description.

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

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

Schema coverage is 100%, but the description adds significant meaning for parameters like min_partition_leg_kelly and min_liquidity, explaining their effect on filter behavior and trade execution. This goes well beyond the schema descriptions.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage, which may cause confusion.

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

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

The description implies usage for discovering betting opportunities without manual browsing, and mentions filtering parameters. However, it lacks explicit guidance on when not to use this tool or how it differs from alternative tools like polymarket_edge_tracker or polymarket_arbitrage.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds valuable behavioral details: history bounded by 60-day TTL, snapshots written on cache-miss, gaps mean no scan, decay from daily closes.

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 front-loaded with the key question. Every sentence adds value, though it could be more structured (e.g., bullet points) for easier scanning.

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

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

No output schema, but the description fully details the return format (tracked, expired, snapshot_dates) and limitations. All parameter effects are explained. Complete for a telemetry tool.

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

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

Schema coverage is 100% with brief descriptions. The description adds meaning by explaining the response structure and clarifying 'window' as snapshot family, and providing defaults. Extra 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 it tracks edge persistence and decay over time, contrasting with current snapshots. It uses specific verbs and distinguishes from sibling tools by focusing on the temporal dimension of edges.

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

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

The description provides context on when to use this tool (e.g., a fresh wide edge vs. an old one), but does not explicitly exclude alternatives or provide when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds detailed behavior: walks the order book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and for baskets: theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk. No contradiction with annotations.

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

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

The description is well-structured with clear sections for single-market and basket modes, uses bold for key terms, and front-loads the purpose. While lengthy, every sentence adds value; minor tightening possible but still efficient.

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

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

Given complexity (two modes, no output schema), the description is very complete. It covers both modes, explains return fields in detail, and warns about forced directional risk and thin legs. No output schema exists, so description must and does fill that gap.

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. The description adds context beyond schema, e.g., for size_usd it clarifies interpretation for buys vs sells and basket mode; for side it explains default auto behavior. Enriches understanding but schema already provides basic info.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and differentiates between single-market and basket modes. It also distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by specific usage guidance.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable on thin books, partial fills create directional risk). Provides clear when-to-use and alternatives.

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

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

The description goes far beyond annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing compatibility_warning conditions, temporal alignment, and skipped cross type/subtype counters. It discloses that most pre-mapped topics return warnings, setting accurate expectations. 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 detailed but somewhat lengthy (150+ words). It front-loads the purpose well but includes verbose safety field explanations that could be condensed. While clear, it 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?

Despite no output schema, the description sufficiently explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, counters). For a complex tool with compatibility logic, this is adequate for an agent to understand and use correctly. A minor gap is lack of default behavior when no parameters are provided.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that topic is a pre-mapped macro shortcut for 10 specific keys and that explicit tickers override mapped ones. This provides semantic context beyond the schema descriptions.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on inter-venue comparison rather than intra-venue arb. The verb 'compute spread' plus resource specification is 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 explains two modes (topic shortcuts and explicit tickers) and provides explicit guidance on when pre-mapped topics may not be tradeable due to compatibility warnings. It implicitly advises caution but does not explicitly state when to use alternatives (e.g., polymarket_edges for edge detection). Still, the context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds value by explaining the scope ('Scoped to your identifier') and the lifecycle pairing with remember/forget. No contradiction with annotations.

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

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

The description is three sentences, all essential: purpose, usage advice, and scope/pairing. No wasted words, front-loaded with the main action.

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

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

For a simple read-only retrieval tool with one optional parameter, the description covers purpose, usage, scope, and relationship to siblings. No output schema is needed, and annotations provide safety. Complete and sufficient.

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

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

Schema coverage is 100% and the schema already documents the key parameter's behavior ('omit to list all keys'). The description repeats this guidance but adds no new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('retrieve' or 'list') and the resource ('value previously saved' or 'all saved keys'). It distinguishes itself from sibling tools 'remember' and 'forget' by explicitly naming them in the pairing 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?

The description provides clear usage context: 'to look up context the agent stored earlier' and 'without re-deriving it from scratch'. It mentions scope (identifier-based) and pairs with remember/forget, but does not explicitly state when not to use or list direct alternatives.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safe read behavior. The description adds key behavioral details: mark_read true flags events as read affecting future calls, and each event carries source, citation_uri, and raw payload. No contradiction with annotations.

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

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

Three concise sentences, front-loaded with the primary purpose, then detailing parameters, side effects, and an alternative access method. Every sentence adds value with no redundancy.

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

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

Given the tool is read-only, idempotent, has full schema coverage, and annotations covering safety, the description is complete. It explains filtering, side effects, and alternative access, leaving no significant gaps for an AI agent to select and 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?

The input schema covers all 5 parameters with descriptions (100% coverage). The description enhances understanding by providing examples ('e.g. sec_8k') and clarifying the effect of mark_read. This adds meaningful context beyond the schema's baseline.

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

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

The description clearly states it pulls fired events from a subscription feed, specifying the resource ('subscription feed') and action ('pull fired events'). It also mentions filtering by type and since, but does not explicitly differentiate from sibling tools like list_subscriptions or search_articles, though contextually distinct.

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 says 'Polls work fine' and mentions an alternative HTTP endpoint for scripts and dashboards, implying usage for polling. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., when to use search_articles instead), nor does it state prerequisites 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 indicate readOnly, idempotent, openWorld, non-destructive. The description adds rich behavioral details: parallel fan-out to multiple sources (SEC, GDELT/GNews fallback, USPTO with soft-fail), date range handling, and return format (changes[] grouped by source, total_changes, citation URIs). No contradictions.

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

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

The description is well-structured, front-loading the purpose and examples. While slightly verbose, every sentence adds value and there is no redundancy.

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

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

The description comprehensively covers the tool's behavior: multiple data sources, fallback mechanisms, soft-failure for patents, date format options, and return structure. No output schema exists, so the description adequately compensates.

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

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

Schema coverage is 100% with descriptions. The description adds practical examples for 'since' (ISO or relative) and specifies that 'value' can be ticker or CIK. This provides additional context 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 provides a change feed for a company over a time window, with specific example queries. It distinguishes itself from sibling entity_profile by noting that entity_profile is for static profiles.

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 example queries (e.g., 'What's new with X', 'latest on Y') and advises when to use entity_profile instead. It also provides guidance on the 'since' parameter, suggesting '30d' or '1m' for typical monitoring.

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 behavioral context beyond annotations: authenticated users get persistent memory, anonymous sessions retain for 24 hours. 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?

Concise yet informative: each sentence adds value, front-loaded with main 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?

Covers persistence, scoping, and pairing. No output schema but store operation doesn't require return value details. Could mention overwrite behavior but adequate overall.

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

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

Schema covers 100% of parameters with descriptions. Description adds examples for key values and states value is any text, enhancing understanding beyond raw schema.

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

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

The description clearly states the tool saves data for reuse, specifies the key-value pair storage, and distinguishes from siblings recall and forget by mentioning 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 says when to use: when discovering something worth carrying forward, with examples (resolved ticker, target address, user preference). Also mentions pairing with recall and forget.

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral context: it lists exact identifier sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), states that unresolved identifiers are explicitly reported under `unresolved` instead of omitted, and specifies graceful degradation when external services are unavailable. This goes far beyond the annotation hints.

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

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

The description is long but information-dense. It starts with example queries to immediately convey use, then states the purpose, and follows with structured details for each supported type. Every sentence adds necessary context—there is no fluff. It could be slightly tightened, but given the tool's dual-type complexity, the length is justified.

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

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

Despite lacking an output schema, the description covers return values comprehensively: canonical identifiers, source labels, unresolved-identifier handling, and enrichment fallback. It also addresses edge cases (service unavailability) and explains the internal cascade, making the tool's behavior predictable. For a two-parameter tool with rich annotations, this is 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?

Although the schema already provides 100% coverage, the description enhances both parameters' semantics. For `type`, it enumerates supported values and maps each to its result behavior. For `value`, it provides example formats (ticker, CIK, name) and distinguishes company vs drug inputs. This adds practical guidance on what to pass and what to expect, exceeding the schema descriptions.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers.' It gives concrete examples of queries ('What's the ticker for…' / 'find the CIK for…') and distinguishes from siblings by positioning it as the first step when a name but no ID is known, while tools like compare_entities and entity_profile operate on already-resolved 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?

Explicit guidance is provided: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups and handles both company and drug types, which clarifies when to invoke this tool versus alternatives. Although it doesn't say 'do not use when', the positive use-case is so clearly scoped that it effectively excludes other situations.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds value by detailing that it probes each entity, ranks by score, and returns per-entity score, confidence, and signal density. 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 four sentences, front-loaded with the core purpose. Every sentence is informative and necessary, with no fluff or repetition.

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

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

Given 4 parameters with full schema coverage, no output schema, and no nested objects, the description adequately explains the tool's output (ranked list with score, confidence, signal density) and usage context, making it complete for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it reiterates the entities parameter's role (first as subject) which is already in the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking by score. It differentiates from sibling ai_visibility_check (single entity) by focusing on multi-entity comparison.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and a concrete example. It implicitly differentiates from ai_visibility_check, but does not explicitly state when not to use or list specific alternatives.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description adds critical behavioral traits: composite fan-out, timing delay for first bundlephobia measurement (5-30s), and graceful degradation with sources_failed reporting. These are not inferrable from annotations alone.

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

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

The description is a single paragraph but is well-structured, starting with the composite purpose and then providing details. It is concise enough (about 150 words) given the complexity. Could be slightly improved with bullet points for the return block, 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?

Despite lacking an output schema, the description thoroughly explains the return value (summary block fields, advisory details, links, alternative versions). It also covers ecosystem scope, default behavior, failure modes, and timing, making the tool completely understandable for agents.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by noting scoped package acceptance ('@types/node') and reiterating default version behavior. It does not add syntactic details beyond the schema, but the extra context on scoped packages justifies a score of 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's a composite check for npm packages combining deps.dev and bundlephobia data. It uses specific verbs ('Scan Dependency') and resource ('npm package'), and distinguishes itself from siblings by noting the NPM-only scope and alternative for other ecosystems.

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

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

Explicitly states when to use: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'.' Also provides context on alternatives for non-NPM ecosystems and details graceful degradation for partial failures.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds return field details, which is useful but not extra behavioral depth 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, no wasted words, front-loaded with key action and result details.

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

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

Given the output schema (implied by returned fields) and high-quality annotations, the description provides sufficient context for the 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 covers 100% of parameters with descriptions. The description only restates the tag filter and pagination, adding no 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 it searches DEV.to articles by tag with pagination, and lists the returned fields, distinguishing it from siblings like get_article or get_articles.

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 when to use (searching by tag) and mentions pagination, but does not explicitly state when not to use or name alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds significant behavioral context: embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping windows), and character cap (200K chars with truncation flag). No contradiction with annotations.

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

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

The description is a single paragraph but is well-structured and front-loaded with the core purpose. Every sentence contributes information, though it could be slightly more condensed without losing clarity.

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

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

The tool has no output schema, so the description must explain return values. It does so by mentioning 'top-N passages with character offsets and similarity scores.' It also covers truncation behavior and the embedding mechanism, making it complete for an AI agent to understand 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%, so the baseline is 3. The description adds value by providing natural-language query examples ('supply-chain risk', 'fiscal year 2024 revenue') and clarifying the text parameter's max length, which goes beyond the schema's description.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the input (text and natural-language query) and output (top-N passages with offsets and scores). It distinguishes itself from siblings like ask_pipeworx_grounded by explaining how they pair together.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains that it saves context by returning only relevant passages. Also provides an alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

The description states 'Returns the new subscription id', implying each call creates a new subscription, which contradicts the idempotentHint: true annotation. This is a significant inconsistency.

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

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

The description is thorough yet efficient, front-loading purpose and organized by sections. No wasted words.

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

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

Despite no output schema, the description covers prerequisites, type variants, delivery options, and webhook signature details, providing all needed 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 description explains each parameter beyond the schema, including type-specific examples and delivery channel details. Schema coverage is 100%.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, distinguishing it from siblings like list_subscriptions and unsubscribe. It names the specific resource and action.

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

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

The description specifies prerequisites (Pipeworx OAuth account) and lists supported types with examples. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds context about the output (category-bucketed examples with tool+argument shapes, drawn from a live catalog) and behavior with/without topic, which goes beyond annotations.

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

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

The description is a single paragraph that front-loads common user questions and then explains functionality. While efficient, it could benefit from bullet points for the list of categories. Still, every sentence adds value.

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

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

Given no output schema, the description thoroughly explains the return content (category-bucketed example questions with tool+argument shapes) and use cases (onboarding, learning). It is fully adequate for an agent to understand and use the tool.

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

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

Schema coverage is 100%. The description explains the single optional parameter 'topic', its possible values (finance, pharma, etc.), and the effect of omitting it (full spread). This adds significant meaning beyond the schema's minimal description.

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

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

The description clearly states that this tool returns category-bucketed example questions about what Pipeworx can do, serving as an onboarding entry point. It distinguishes from siblings by focusing on getting started and learning what to ask, unlike query tools (ask_pipeworx) or research tools (deep_research).

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

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

Explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains when to omit or pass the topic parameter, and implicitly distinguishes from other tools by listing them as things to learn about.

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 a write operation (readOnlyHint: false) and non-destructive (destructiveHint: false). The description adds that ownership is enforced and rows are deactivated not deleted, providing useful behavioral context beyond annotations.

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

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

Three sentences with no wasted words. The purpose is stated first, followed by key behavioral details.

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

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

For a simple single-parameter tool with no output schema, the description adequately covers ownership, deletion behavior, and impact on historical data.

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

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

Schema coverage is 100% and the description adds minor context by noting the id is 'returned by subscribe', but does not provide significant additional 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 action ('Cancel a subscription by id') and distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by noting ownership enforcement and soft deletion.

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

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

The description provides clear context for when to use the tool (cancel by id) and mentions ownership enforcement, but does not explicitly list when not to use it or compare to alternatives.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description adds important behavioral nuance beyond these: could_not_verify is explicitly defined as 'the check did not happen' and 'must not be shown as one,' while unsupported is distinguished as 'we looked and cover no source for it.' It also details the two routing paths (SEC EDGAR + XBRL fast path vs. grounded pipeline) and the return shape.

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

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

The description is longer than a one-liner, but every sentence earns its place: trigger phrases, routing logic, return contract, and a caller warning about could_not_verify are all compressed into a structured flow. The front-loaded natural-language examples immediately signal the tool's purpose, and the 'IMPORTANT for callers' section is a clear, high-value addition.

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?

Even without an output schema, the description fully enumerates return components 'verdict ... actual value with pipeworx:// citation, and reasoning' and explains the interpretation of could_not_verify and unsupported. It also covers both company-financial and general claims, the source-routing behavior, and the fallback semantics, making the tool's behavior sufficiently clear for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, with rich descriptions for both `claim` and `tolerance_pct` already including examples and threshold guidance. The description adds general context about 'exact percent-delta math' but does not provide additional parameter-specific meaning beyond what the schema offers, 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?

The description opens with a specific verb+resource pairing: 'natural-language claim verification against authoritative sources' and explicitly states the tool checks 'whether something a user said is factually correct.' It further distinguishes itself by listing the returned verdict types and noting it replaces 4–6 sequential steps, making it clearly distinct from sibling tools.

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

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

The description includes an explicit trigger: 'Use whenever the agent needs to check whether something a user said is factually correct,' and it differentiates between company-financial claims and other factual claims via routing. It does not name alternative sibling tools or provide formal when-not-to-use conditions, but the context is clear enough to guide selection.

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