Data Nola

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds cost implications for Anthropic probes, return format structure, and default model behavior, exceeding what annotations provide.

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

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

Three sentences, front-loaded with action verb and resource, no wasted words. Efficiently covers purpose, usage, and behavior.

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 purpose, parameters, usage, and return format. Lacks detail on scoring algorithm or signal interpretation, but sufficient given no output schema and 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 adds meaningful context for each parameter: explains entity purpose, supported models, _apiKey requirement, and context disambiguation. Provides value beyond schema.

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

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

Description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility. Distinguishes from sibling tools by focusing on visibility scoring and model-specific probing.

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

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

Provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly state when not to use or contrast with alternatives like deep_research or ask_pipeworx.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond these hints: it's the 'default entry point', 'works on every tier', and is 'one fast call', while also revealing it returns structured answers with citations. It doesn't expose limitations like potential failures, but with rich annotations the bar is lower, making this solid.

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

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

The description is long but every sentence earns its place: it front-loads the key instruction, then lists use cases, mechanics, examples, and alternatives in a logical flow. It is not excessively verbose for the amount of guidance it provides, earning a high score.

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 (routing to thousands of sources), the description is remarkably complete: it covers what types of questions it handles, how it works, when to escalate, and includes concrete examples. The absence of an output schema is compensated by the explanation that it returns 'structured answer with stable pipeworx:// citation URIs'.

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 all six parameters described as aliases for 'question'. The description adds semantic richness through real-world examples ('current US unemployment rate', 'Apple's latest 10-K', 'patents Tesla was granted last month') that clarify the expected input style, going beyond the schema's plain definition.

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 'routes the question to the right one of 5,529 tools... returns the structured answer with stable pipeworx:// citation URIs,' making the function obvious. It differentiates from siblings by naming when to use ask_pipeworx_grounded and deep_research instead, so it does more than just restate the name.

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

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

The description explicitly states 'PREFER OVER WEB SEARCH' and gives a comprehensive list of applicable domains (SEC filings, FDA data, economics, etc.), plus example phrasings. It provides direct alternatives: 'use ask_pipeworx_grounded' for hallucination-resistant answers and 'use deep_research' for broad/multi-part questions, covering when-not-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?

Annotations already declare read-only, idempotent, and open-world behavior, lowering the burden. The description adds valuable context about its beta/experimental nature, current status (no active candidate), and full working capability, which goes beyond the structured annotations.

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

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

The description is front-loaded with the core definition and includes useful details about status and usage. Each sentence contributes, though the phrase 'Falls back to nothing' is slightly confusing and could be streamlined.

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

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

The tool is a complex universal router with no output schema, but the description clarifies it shares the same response shape as ask_pipeworx, providing necessary context. It covers the beta nature, current behavior, and usage, making it adequately complete for the 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?

The input schema provides 100% coverage for all six parameters, documenting each as an alias for the 'question' field. The description mentions 'same arguments' but does not add new meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router, and differentiates it from siblings by mentioning candidate routing improvements and the experimental edge. It specifies the scope (same 5,529 tools, same arguments) and current behavior, making the purpose unambiguous.

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

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

The description explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also contrasts with the stable router and mentions that results are compared to decide merges, giving clear context for when the beta variant is appropriate.

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

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

The description goes far beyond the annotations by disclosing the internal process (routing, fetching, extracting only from tool result), the exact return structure with evidence and refusal reasons, and the cost of one extra LLM call. It adds significant context about failure modes and guarantees, which annotations do not provide.

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

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

The description is dense but well-structured: purpose, mechanism, return format, usage guidance, cost. Every sentence adds value and the most important information is front-loaded. It is concise for the amount of behavioral detail provided.

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

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

Given no output schema, the description fully explains return values, refusal reasons, and success/error behavior. It also covers routing, cost, and usage context, making it complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add any parameter-specific meaning, but the schema fully documents the 'question' parameter and its aliases, so no additional semantics are necessary.

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 is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from ask_pipeworx by emphasizing that it extracts answers using only the tool's result, returning evidence and explicit refusals. This gives a specific verb, resource, and behavioral scope that differentiates it from siblings.

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

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

Explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'), including cost trade-off. Also lists example high-stakes domains.

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 safe read-only operation. The description adds extensive behavioral context: fan-out logic by classifier, resolver contract with confidence levels, parent event extraction, news fallback mechanism (GDELT 429s, GNews backfill), safety short-circuits, tradeability warnings, and resolution-rule parsing. It even describes practical behavior like de-indexed markets surfacing via low-confidence path.

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

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

The description is very long (700+ words) and dense with information. While front-loaded with a clear summary, the lack of structural headings (e.g., paragraphs for sections) and excessive detail make it less concise. However, the complexity of the tool justifies the length, and each detail serves a purpose for agent decision-making.

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, rich behavioral logic), the description is exceptionally complete. It covers input interpretation, classification, fan-out, response shapes, resolver contract, parent events, news fields, safety, tradeability, and resolution-rule risk. No significant gaps remain for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, providing baseline clarity. The description adds value beyond schema: it clarifies that 'market' accepts slug, URL, or text (already in schema but reinforced), explains 'depth' enum ('quick = 2-3 sources, thorough = full fan-out. Default thorough'), and provides guidance on 'include_raw' (summarized vs full payloads, size implications, use cases). This goes beyond bare 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies multiple input formats (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). This distinguishes it from sibling tools like polymarket_edges by being the primary research tool for betting queries.

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

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

Explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides detailed guidance on inspecting market_match_confidence, handling low-confidence matches, closed markets, wide spreads, and resolution-rule risk. Includes practical notes on when results are blocking (low_confidence_match, market_closed_or_inactive).

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?

Disclosures about data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorted results, and citation URIs add significant value beyond annotations which already indicate read-only, idempotent, and non-destructive 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 front-loaded with natural language triggers, but slightly verbose. However, each sentence adds essential context, leaving minimal 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 (two entity types, multiple data sources, sorting) and absence of output schema, the description thoroughly explains behavior, inputs, and return structure, making it self-sufficient for agent selection.

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

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

With 100% schema coverage, the description enriches parameter meaning by detailing what each 'type' returns (financial metrics for company, safety/trial stats for drug) and clarifying that 'values' uses tickers/CIKs for companies and drug names.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes from sibling tools like entity_profile by emphasizing efficiency over sequential lookups.

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

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

Explicitly advises ALWAYS PREFER over sequential single-pack lookups when comparing entities, with example queries. While it doesn't explicitly exclude non-comparison tasks, the context strongly implies comparison use cases.

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

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

Annotations already declare readOnly/openWorld/idempotent/destructive hints, but the description adds materially: account/auth requirements, paid tier for thorough depth, expected latency, never-invented gaps[], semantic excerpting, contradictions[] scan, and fetchable citation_uri. There is 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?

Although long, the description is front-loaded (account requirement and alternative tool first) and every clause adds distinct information—alternatives, behavior, output format, latency—with zero filler. The dense paragraph structure is acceptable for the amount of guidance provided.

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

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

Given no output schema, the description fully specifies return semantics: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and hop field. It also covers failure modes (empty gaps[] for uncatalogued news), latency, and depth differences, so an agent has everything needed to invoke correctly.

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

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

Schema covers both params (100%), but the description deepens the depth enum with explicit facet counts, hop behavior, gap recovery, paid tier, and contradictions scan. It also clarifies the question param is broad/multi-part because decomposition is built-in — meaningfully beyond the schema's minimal descriptions.

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

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

The description opens with a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly states 'this is NOT open-web search.' It also distinguishes from siblings by naming ask_pipeworx for single lookups and news topics, so the purpose is 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?

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data,' and exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' It also covers account/auth prerequisites and a fallback alternative, which is textbook usage 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 readOnlyHint=true and idempotentHint=true. The description adds behavioral context: returns top-N relevant tools with full schemas and curated examples, and that each result is ready to call directly—no second lookup 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 well-structured and front-loaded with the core purpose, followed by usage guidance and return details. It is concise but could be slightly tighter by reducing repeated enumerations.

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

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

Given the tool's simplicity (1 required param, no output schema), the description covers purpose, usage, return format, and examples. It is complete enough for an agent to understand when and how to invoke it.

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

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

Schema description coverage is 100%. The description adds value by explaining that the main parameter is a natural language description and listing accepted aliases (task, q, description, search), along with examples.

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

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

The description uses a specific verb+resource ('Find tools by describing the data or task') and clearly distinguishes the tool from siblings by highlighting its role as a tool discovery/search mechanism, listing concrete data domains (SEC filings, FDA drugs, etc.).

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

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

The description explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It provides clear usage context but does not mention specific alternatives among sibling 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?

Beyond annotations (readOnly, openWorld, idempotent), the description discloses multi-source fan-out, specific data returned, patent sunsetting, and news fallback. Provides thorough behavioral context.

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

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

Description is lengthy but every sentence adds value, front-loaded with example queries. Could be slightly more compact but remains clear and structured.

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

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

Despite no output schema, the description lists all output components (CIK, filings, fundamentals, patents, news, LEI) with details like sorting and URIs. Complete for a complex multi-source tool.

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

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

Schema coverage is 100% but description adds critical context: type is currently only 'company', value must be ticker or zero-padded CIK, names not supported, and directs to resolve_entity for names. 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 provides a full cross-source profile of a US public company, lists specific queries users can make, and distinguishes it from chaining individual lookups. It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'.

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

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

The description gives explicit guidance on when to use (holistic view requests) and when not to (names not supported; use resolve_entity first). It also mentions fallback behavior for patents and news.

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

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

Annotations already indicate destructiveHint=true. The description adds behavioral context: clearing sensitive data and using when stale/done. No contradictions.

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

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

Two sentences, front-loaded with purpose, no wasted words. Highly concise.

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

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

Simple tool with one required parameter. Covers purpose, usage context, and relationship to other tools. No output schema needed.

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

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

Schema coverage is 100% and describes the 'key' parameter as 'Memory key to delete'. The description does not add additional parameter semantics beyond this.

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 deletes a memory by key. It uses a specific verb ('delete') and resource ('memory'), and distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use: when context is stale, task done, or to clear sensitive data. Also mentions pairing with 'remember' and 'recall', providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds operational details (fetches page, extracts title/description/links, emits standard markdown). No contradictions. Could note error handling or rate limits but acceptable for a read-only tool.

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

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

Two concise sentences plus a bullet list. All sentences carry unique value. Front-loaded with the main action. No filler.

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

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

Even without output schema, the description explains the return format ('single text blob ready to drop at site-root/llms.txt'). Annotations provide safety context. Complete for a simple generation 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% with clear descriptions for both parameters. The description adds minimal extra meaning (e.g., full URL example). Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states the tool generates an llms.txt file, with specific verb 'generate' and resource 'llms.txt file'. It uniquely distinguishes from sibling tools like ai_visibility_check by specifying the format and use case.

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

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

The description lists three explicit use cases (client indexing, own project drafting, competitor auditing). It does not directly contrast with siblings but implies appropriate contexts. Lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds specific return fields and implies default behavior (active only). No contradictions.

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

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

Two sentences, front-loaded with the core action, no redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, description sufficiently covers behavior and return fields.

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

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

The single parameter (include_inactive) is fully described in the input schema; the description does not add further detail beyond 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?

Clearly states the tool lists the caller's active subscriptions and enumerates the returned fields (id, type, etc.). Distinguishes from siblings like subscribe and unsubscribe.

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

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

Provides explicit use cases: reviewing monitored subscriptions before adding more, or finding an ID to cancel. Gives practical context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. Description adds context about the specific data source (data.nola.gov) and output fields, but does not disclose pagination behavior, rate limits, or authorization details beyond what schema provides.

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

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

Two concise sentences, front-loaded with the core action. Every phrase adds value: target catalogue, action, return values, and linkage to related tool. No wasted words.

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

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

For a simple search tool with full annotations and schema, the description covers the essential purpose and output usage. Could benefit from a brief note on pagination (limit/offset) or that results are paginated, but not critical.

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

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

Input schema covers all 4 parameters with full descriptions (100% coverage). Description adds no new semantic information about parameters, only reiterating 'by keyword' which aligns with the query param. Meets baseline for high schema coverage.

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

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

Description clearly states it searches the New Orleans open-data catalogue by keyword, specifying the resource and action. It also mentions the return type (names, descriptions, resource ids) and ties to sibling nola_query, distinguishing its output.

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

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

No guidance on when to use this tool versus siblings like nola_recent. Does not specify prerequisites or when not to use. Only implies usage chain with nola_query, insufficient for tool selection.

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

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint. The description adds that it runs raw SQL-like queries, which is consistent. No additional behavioral traits are disclosed beyond what annotations imply, but no contradiction.

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

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

The description is two sentences, front-loading the core purpose and providing essential usage guidance without extraneous information.

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

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

Given 8 parameters with full schema coverage and annotations indicating safety, the description adequately explains the tool's purpose and usage. The lack of an output schema is acceptable as the tool returns raw query results. The description could mention pagination behavior, but overall it 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?

Schema description coverage is 100%, so baseline is 3. The description mentions the SoQL clauses that correspond to parameters but does not add significant meaning beyond the schema descriptions (e.g., 'SoQL $group'). The examples in the schema provide more context.

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

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

The description clearly states it runs raw SoQL queries against New Orleans open data, specifying the resource ID format and available SoQL clauses. It also distinguishes from sibling tools nola_datasets and nola_recent by directing users to those for finding resource IDs.

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 nola_datasets or nola_recent to find resource IDs before using this tool. It does not specify when not to use the tool, but the context of alternatives 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, idempotentHint, and non-destructive behavior. The description adds context that results are returned newest-first and supports optional filtering via SoQL where clause. It does not contradict annotations and provides useful behavioral details beyond what annotations offer.

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

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

Extremely concise: two sentences plus a list of dataset names. The core purpose is front-loaded, followed by usage preference and parameter hints. No wasted words; every sentence adds value.

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

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

Given no output schema, the description explains the return order (newest-first) and the ability to limit and filter. However, it does not mention that the column structure may vary per dataset, which could be useful. Overall, it is fairly complete for a simple data retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by naming the allowed dataset values (311, crime, permits) and explaining that the 'where' parameter is a SoQL filter. Examples further clarify usage, going beyond the schema's property descriptions.

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

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

The description explicitly states it retrieves recent records from common New Orleans open datasets using friendly names, avoiding the need for a Socrata identifier. It distinguishes itself from the sibling tool 'nola_query' by specifying this tool is for simple recent data retrieval.

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

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

Provides explicit guidance to prefer this tool over web search for specific queries like 'recent crime in New Orleans', and directs users to use 'nola_query' for more complex needs. This clearly differentiates when to use this tool versus 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?

With all annotation hints false, the description adds substantial behavioral context: rate-limiting (5/day), free usage, no quota impact, claim_token workflow for later status checks, and the team's daily digest reading. It also gives content handling guidance (don't paste the end-user's prompt), which is valuable beyond annotations.

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

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

The description is long but every sentence earns its place: purpose, use cases, exclusions, claim_token workflow, policy, and quota. It is front-loaded with the core function, then logically flows through exceptions and operational details 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?

The description covers purpose, alternatives, exclusions, return behavior (via claim_token), rate limits, and content guidelines. Given the tool has no output schema and a nested context object, it sufficiently explains the expected behavior and constraints for an agent to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the claim_token workflow (pass back with no other arguments) and instructing users to describe issues in terms of Pipeworx tools/packs, which complements the message parameter. However, the type parameter's enum semantics are fully covered by the schema, so the marginal addition is modest.

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

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

The description uses the specific verb 'Tell' (Send) and identifies the resource (Pipeworx team). It clearly distinguishes this tool from siblings by focusing on feedback about Pipeworx tools, with explicit mention of bug/feature/data_gap/praise categories.

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

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

It explicitly states when to use the tool ('Use when a tool returns wrong/stale data...') and when not to ('if the tool came from a different MCP server... file it with that server instead'). It also offers a decision heuristic for identifying Pipeworx tools, which is above average.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds valuable context: data source ('CF analytics-engine'), privacy ('no PII'), and caching behavior ('Cached 5min-1h'), which are beyond schema and 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 with no fluff: first sentence defines the output, second lists use cases, third adds caching and data source details. It is front-loaded and every sentence earns its place.

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

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

Given low complexity (1 optional param, no output schema), the description covers all needed aspects: return structure, data provenance, privacy, caching, and use cases. No gaps remain for an agent to use the tool correctly.

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

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

With 100% schema coverage and a single parameter 'window' already described, the tool description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances the schema's enum explanation.

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 'Returns the top tools, top packs, and total call volume over a recent window,' specifying a precise verb ('returns') and resource (trending data). It distinguishes itself from siblings like 'discover_tools' or 'ask_pipeworx' by focusing on aggregated call volume.

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?

Three explicit use cases are provided (discovering hot data sources, confirming canonical tools, aligning use case). However, it does not explicitly mention when not to use or provide direct comparisons to 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: internal thresholds (3pp deviation, 0.30 Jaccard similarity, 20% placeholder fraction), the fill check logic with realizable_edge_pp, and response structure. No contradictions with annotations.

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

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

The description is well-structured with clear sections for each mode and internal logic. It is front-loaded with the core purpose. However, it is somewhat verbose, including detailed technical thresholds that could be seen as implementation details. Every sentence earns its place, but condensing some internal checks could improve conciseness.

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

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

The tool has no output schema, so the description must describe return values. It does so thoroughly: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and for event mode 'partition_check{...}'. It also covers edge cases like skipped_low_similarity and placeholder filters. Given the complexity (2 optional parameters, multiple modes, internal checks), the description is complete and practical.

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 substantial value beyond the schema: it explains the default behavior when no args are passed (trending scan), provides examples of valid slugs and topics, and details what each mode does internally. However, the schema descriptions themselves are already clear, so the addition is incremental but significant.

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 purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes between the three modes (no args, event, topic) and provides specific examples of when to use each. This fully differentiates it from sibling tools 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 parameter: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. It includes examples of slugs and seed questions, explains the fill check as a prerequisite for trading, and even references an alternative tool (polymarket_fill_risk) for custom sizing. This is comprehensive and leaves no ambiguity.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and no destructive behavior. The description adds extensive context: caching, slippage treatment, Kelly fractions, market move warnings, and segment diagnostics. No contradictions with annotations.

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

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

The description is comprehensive but overly long (~300 words). It is front-loaded with purpose but then delves into excessive model detail. While well-structured into segments, it sacrifices conciseness for completeness.

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 9 parameters, no output schema, and annotations providing read/idempotent hints, the description fully explains response structure (by_segment, diagnostics), model families, and edge computation. It is sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining rationale (e.g., slippage_pp discusses Polymarket fees, min_partition_leg_kelly explains why min_kelly doesn't filter partition arbs). It enriches but is not critical.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, using a specific verb-resource combination. It differentiates from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge detection across multiple model families.

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 frames usage for 'what should I bet on today' and mentions discovering opportunities without paging. It also describes adjustable knobs and filters. However, it lacks explicit when-not-to-use guidance or direct comparison to sibling tools.

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

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

Annotations already declare readOnly, openWorld, idempotent. The description adds significant behavioral details: snapshot cache-miss gaps, 60-day TTL limit, decay computation from daily closes with net slippage, and the meaning of negative values. 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 relatively long but well-structured, front-loading the core question and then detailing response and limitations. Each sentence adds value, though slightly verbose.

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

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

No output schema, so description thoroughly explains return fields (tracked[], expired[], snapshot_dates[]) and their semantics. Also covers data gaps, TTL, and decay details. Very complete for a tool with two optional parameters.

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

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

Schema covers parameters 100% with descriptions. The description adds minor context like snapshot family and default/limits, but does not substantially extend beyond schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from siblings like polymarket_edges by focusing on time-series analysis of edge existence and trend.

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

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

The description explains when to use the tool via the example of fresh vs old wide edges, but it does not explicitly state when not to use or compare with siblings like polymarket_edges. Still provides clear context for usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, so safety is clear. Description adds rich behavioral detail: 'walks the ladder,' returns verdict categories (clean|degraded|cannot_fill), explains basket mode risks like forced_directional_risk and thin_legs, and warns that partial basket fills convert arb into unhedged directional position. No contradiction with annotations.

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

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

Description is detailed but every sentence provides essential information. It is front-loaded with core purpose, then structured into requirements, mode details, return fields, and usage guidelines. Could be slightly more bulleted for readability, but as prose it is efficient and clear.

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

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

Given the complexity (two modes, multiple return fields, risk warnings) and lack of output schema, the description is highly complete. It covers all parameters, explains output fields per mode, includes thresholds (clamp), and highlights critical risks. No gaps for an experienced user.

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 good parameter descriptions. Description adds value by explaining default behavior for side (auto in basket), interpreting size_usd in basket mode as 'settlement notional,' and grouping parameters by mode. 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?

Description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' specifying the verb (check), resource (edge), and scope (against live book). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on 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?

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable, partial fills cause directional risk) and implies when not to use (trades below $500). Provides clear context and exclusions.

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

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

Annotations (readOnlyHint=true, etc.) already indicate safety, but description adds extensive behavioral details: compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype counters, and explanation of when spreads are meaningful. 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?

Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and keyword emphasis. However, it is verbose with many details; could be tightened slightly without losing value.

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

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

Despite no output schema, the description fully explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields). Covers all aspects an agent needs to interpret results.

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

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

Schema coverage 100% with descriptions for all 3 parameters. Description adds context: topic list values and explanation that explicit params override topic-mapped sides. Very helpful but schema already carries the 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?

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, with two explicit modes (topic shortcuts and custom pairing). Distinguishes from sibling 'polymarket_arbitrage' by focusing on cross-venue 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?

Explicitly describes two usage modes with examples and warns that pre-mapped topics may not be tradeable (compatibility_warning). Provides clear when-to-use guidance including limitations.

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, idempotentHint, destructiveHint, so the safety profile is clear. The description adds useful context about scoping to identifier and the listing behavior, going beyond the annotations. It does not contradict the annotations.

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

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

The description is concise (two sentences) and front-loaded with the core action. Every sentence adds value without redundancy.

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

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

For a simple read/list tool with full annotation coverage and one parameter, the description is largely complete. It covers purpose, usage, scoping, and pairing. It lacks explicit mention of return behavior (e.g., what happens if key not found), but this is minor given the tool's simplicity.

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

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

The input schema has 100% coverage, with a clear description for the 'key' parameter. The description adds no new semantic beyond the schema (it repeats the omitting-to-list behavior). The extra context about pairing is valuable but not directly about parameter semantics.

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

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

The description clearly states the tool's function: retrieve a value by key or list all keys. It uses specific verbs ('Retrieve', 'list') and distinguishes itself from siblings 'remember' and 'forget' by naming them explicitly.

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

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

The description explains when to use the tool ('look up context stored earlier', 'without re-deriving') and provides scoping details. It does not explicitly state when not to use it, but the context is sufficient and references alternative actions ('Pair with remember', '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?

The description adds critical behavioral context beyond annotations: it explains that setting mark_read:true flags events as read, affecting subsequent calls. This is important for a tool with readOnlyHint=true, as it reveals a state-changing side effect. No contradictions with annotations.

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

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

The description is concise (several sentences), front-loaded with the core purpose, and every sentence adds value without redundancy or fluff.

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

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

Given 5 optional parameters and no output schema, the description covers return fields, filtering, state management via mark_read, and even provides an alternative direct HTTP endpoint. It is comprehensive for a read tool.

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

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

With 100% schema coverage, the description still adds meaning by providing example filter values (e.g., 'sec_8k'), explaining the behavior of mark_read, and detailing return fields. This enriches the agent's understanding beyond the schema.

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

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

The description clearly states the tool pulls fired events from the subscription feed, returns recent alerts with specific fields (source, citation_uri, raw payload), and distinguishes it from sibling tools like subscribe, unsubscribe, and list_subscriptions by focusing on fetching alerts.

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

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

The description provides guidance on when to use (pulling fired events, polling) and mentions an alternative access method via HTTP for scripts/dashboards. However, it lacks explicit when-not-to-use scenarios or comparisons to similar tools like recall or remember.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: parallel calls to multiple sources, fallback mechanism, soft-fails for USPTO, date format flexibility, and return structure with source-grouped changes 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?

The description is well-structured: front-loaded with use cases, then explains the parallel call, sources, date format, return format, and alternative tool in a dense but efficient manner. Every sentence serves a purpose.

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

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

Despite no output schema, the description explains the return structure (changes[] grouped by source, total_changes count, pipeworx:// URIs) and mentions edge cases (soft-fail for USPTO, fallback). For a 3-parameter tool, this covers input, behavior, and output fully.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining relative date shorthand ('30d', '1m') and providing examples ('30d' or '1m for typical monitoring'). It also clarifies 'value' can be ticker or CIK. This goes beyond the schema's basic 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: a change feed for a company over a time window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It explicitly distinguishes from the sibling 'entity_profile', which provides a static profile.

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

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

The description provides explicit usage scenarios ('What's new with X', 'latest on Y') and when to use alternatives ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior (GDELT→GNews).

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: storage mechanism (key-value scoped by identifier), persistence differences (authenticated vs anonymous), and pairing with other tools. 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?

Four sentences with zero waste: purpose first, then usage guidance, then behavioral details. Efficiently front-loaded.

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

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

Fully explains what the tool does, when to use, how data is stored, and retention policy. No output schema needed for a simple write operation.

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

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

Schema coverage is 100% so baseline is 3; description adds meaningful context by providing example key patterns ('resolved ticker', 'target address') and value types, raising it 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 clearly states 'Save data the agent will need to reuse later' (specific verb+resource) and distinguishes from siblings like recall and forget.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and lists example scenarios; also pairs with recall and forget for retrieval/deletion.

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

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

The annotations already cover readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable behavioral context: identifiers are labelled with their source, unresolved ones are explicitly stated rather than omitted, FIGI resolution depends on implied ticker, and GLEIF/OpenFIGI unavailability degrades gracefully while EDGAR data still returns. 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 lengthy but well-organized. It front-loads with example queries, then defines supported types, each with key output details, unresolved handling, and graceful degradation. Every sentence contributes value; no filler or redundancy. The structure supports quick scanning for the essential usage rules.

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

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

There is no output schema, so the description must explain return behavior. It covers the identifiers returned per type, source labelling, unresolved identifier handling, and failure mode degradation. For a resolver tool with two entity types and multiple identifier sources, this is highly complete. It even notes that it replaces multiple manual lookups, giving operational 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%, so the baseline is 3. The description mostly reiterates what the schema already states (e.g., 'accepts ticker, CIK, or company name' appears in both). It does add some nuance like 'ticker is implied' and source-specific behavior, but these are more about output behavior than parameter semantics. The description does not substantially deepen the schema's parameter meanings.

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 is crystal clear: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names specific verbs ('resolve', 'look up'), targets ('company', 'drug'), and gives example queries. It explicitly instructs 'Use FIRST' and lists the exact identifier outputs, distinguishing it from siblings like entity_profile or compare_entities.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' which provides a strong when-to-use directive. It also details supported types and input formats, and says it 'replaces 2-3 manual lookups.' However, it does not explicitly mention when not to use it or name alternative tools, which prevents a perfect score.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details like probing each entity, returning ranked list with score, confidence, signal density, and mentions API key requirement for Anthropic model. No contradictions.

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

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

Two concise sentences, zero wasted words. Front-loaded with core purpose, then details. Every sentence earns its place.

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

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

No output schema exists, but description fully describes return format (ranked list with score, confidence, signal density). Input constraints (2-8 entities), side effects (none, idempotent), and permissions are implied. Complete for a comparison tool.

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

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

Schema description coverage is 100% (all 4 parameters have descriptions). Description adds valuable context beyond schema: first entity treated as subject, supported models details, and shared context purpose. Reinforces but does not fully replace schema.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, ranks them, and identifies most/least recognized. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (different type of 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?

Explicitly frames usage for competitive AI-marketing audits with an example question. Implies when to use (comparing multiple entities) and when not (single entity check would use ai_visibility_check). Provides clear context.

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

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

Description adds value beyond annotations: explains partial failures, slow bundlephobia first measurement (5-30s), and graceful degradation with sources_failed. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness.

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

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

Single paragraph, dense but well-organized. Front-loaded purpose and data sources. Could be slightly more structured, but 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?

No output schema, but description fully enumerates return fields (summary block, per-advisory detail, links, alternative versions) and explains failure modes. Holistically covers what the agent needs to know.

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

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

Schema coverage is 100%, but description adds practical context: scoped packages accepted for 'package', version defaults to latest. Slightly above baseline.

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

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

Description clearly identifies the verb ('composite check'), resource (npm package), and data sources (deps.dev and bundlephobia). Distinguishes from siblings by noting NPM-only scope and directing other ecosystems to deps.dev:version.

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

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

Explicitly states when to use ('is X safe / popular / small' or 'what does adding lodash cost me') and when not (non-NPM ecosystems). Provides alternative ('deps.dev:version directly'), meeting the highest standard.

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 the model (BGE-base-en), windowing (500-char overlapping), character offsets, and a 200K char cap with truncation flag. No contradictions with annotations.

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

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

Concise at ~120 words, front-loaded with purpose, every sentence adds value (usage scenario, technical details, limits). No unnecessary content.

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

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

Comprehensive given the tool's simplicity: covers input, behavior, limits, pairing, and return structure (character offsets and similarity scores). No output schema needed for understanding.

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 some examples (e.g., query examples) but mostly reiterates schema info (max chars, limit range). Marginal added value over 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 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article). It distinguishes from sibling tools like ask_pipeworx_grounded by explaining when to use search_within and how it pairs 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 'Use when the record is too big to cram into the prompt' and describes pairing with ask_pipeworx_grounded. This provides clear guidance on when to use this tool versus 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?

Exceeds annotations by detailing return value ('Returns the new subscription id'), limitations (SMS 10/day cap, webhook auto-disable after 10 failures), and prerequisites (verified phone). 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?

Lengthy but well-structured and efficient. Front-loaded with core purpose, then requirements, types, and delivery. Every sentence adds value; 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?

Covers prerequisites, types, delivery options, and limitations. No output schema, but return value is mentioned. Could briefly note that subscriptions are persistent and manageable via other tools, but not essential.

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 adds substantial meaning to each parameter: explains type-specific filter structures (e.g., sec_8k items codes), delivery channel details (webhook HMAC signing, auto-disable). Highly enriches the schema.

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

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

The description clearly states the verb ('Create') and resource ('proactive monitoring subscription to a live-data event stream'). It distinguishes this from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

Provides explicit context: requires Pipeworx OAuth account, with clear examples for supported types and delivery channels. No direct when-not-to-use, but the context is sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it returns example questions with exact tool+argument shapes from the live catalog, providing context beyond annotations.

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

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

The description is informative and well-structured, starting with typical prompts and covering usage. Each sentence adds value, though slightly long but not excessive.

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 one optional parameter, no output schema, and rich annotations, the description is fully complete: explains purpose, parameters, return contents, usage timing, and scope without gaps.

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

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

Schema coverage is 100% for the only parameter 'topic'. Description adds example values and explains behavior when omitted, adding meaning beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions and positions it as the onboarding entry point, distinguishing it from sibling tools like ask_pipeworx and discover_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?

Explicit guidance to use 'FIRST' when the user doesn't know what Pipeworx can do, and optional topic parameter to focus. No exclusions or alternatives mentioned, 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?

The description adds behavioral context beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' Annotations indicate non-destructive and idempotent, but description fills in the details.

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

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

Description is two sentences with no extraneous words. It front-loads the action and then adds key constraints and side effects efficiently.

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

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

Given one parameter, no output schema, and annotations covering safety, the description explains ownership and the deactivation behavior, making it fully adequate for correct invocation.

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

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

Schema coverage is 100% for the single parameter 'id', described as 'Subscription id (uuid) returned by subscribe.' The description does not add significant meaning beyond the schema, baseline score of 3 applies.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It includes a specific verb and resource, and distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description specifies ownership enforcement, indicating when the tool can be used (your own subscriptions) and when it cannot (others'). It lacks explicit exclusion or alternative tool mentions, but provides clear context.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds rich context: the SEC EDGAR fast path for company-financial claims, fallback to grounded pipeline for any other claim, and the exact meaning of 'could_not_verify' vs 'unsupported' with a verification_error object. It warns callers not to treat could_not_verify as evidence for/against the claim. This is far beyond annotation coverage and has no contradiction.

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

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

The description is front-loaded with trigger phrases, and every sentence earns its place. Despite being long, it is well-structured: what it does, when to use, routing rules, return payload, and critical caller caveats. No redundancy or filler.

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

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

With no output schema, the description fully covers return values (verdict types, actual value, citation, reasoning) and error semantics. It also explains the two execution paths and the tool's role as a replacement for 4–6 sequential calls. The description leaves no significant questions unanswered for the agent.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful semantics: it explains tolerance_pct overrides the wording-implied tolerance, gives concrete example use (1–2 for hallucination detection), and provides example claim formats for the claim parameter. This elevates the parameter understanding well beyond 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 verifies natural-language factual claims against authoritative sources, lists trigger phrases, and distinguishes it from sequential multi-step approaches. It names a specific verb (validate/verify), resource (authoritative sources), and scope (any factual claim, with a fast path for company-financial claims).

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two routing paths. It does not explicitly name alternative sibling tools but clarifies this replaces 4–6 sequential calls, implying the alternative is manual decomposition. There are no exclusions or when-not-to-use, but the guidance is clear enough.

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