Data Dallas

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

Adds value beyond annotations by describing return format (per-model score, confidence, signals, raw_response + combined view), cost implications (free vs BYO key), and default model behavior. 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?

Two concise paragraphs with clear front-loading of core functionality in first sentence. 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?

Explains return format and use cases adequately for a read-only tool with 4 parameters and no output schema. Slightly more detail on output structure could be helpful but not necessary.

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

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

Schema coverage is 100% with each parameter described. The description reinforces entity purpose, default model, and _apiKey usage but does not add significant new 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?

Uses specific verb 'probe' and resource 'LLMs', clearly states scoring visibility 0-100 per model, and distinguishes from sibling tools like 'compare_entities' and 'scan_competitor_ai_presence' through its focus on LLM knowledge and scoring.

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

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

Explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and differentiates between free default model and BYO-key Anthropic. However, does not explicitly state when not to use or compare to alternatives.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: it routes to a massive tool ecosystem, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier. This complements the annotations without contradicting them.

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 its most important directive ('PREFER OVER WEB SEARCH') and organized with clear examples and alternative tool guidance. It is longer than strictly necessary, with some redundancy around 'even if web search could also answer it', but every section serves a distinct 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?

For a tool with this complexity—routing to 5,529 tools and 1,455 sources—the description covers usage, selection criteria, alternatives, examples, and output characteristics (structured answer with citations). The input schema and annotations are also rich, so the description is complete enough for an agent to confidently 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 coverage is 100%, with the question parameter well-described and aliases listed. The description enriches this by providing concrete examples of valid questions and clarifying that any factual query about real-world entities is acceptable, helping the agent understand the semantic breadth of the parameter.

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: it routes factual questions to a vast array of verified sources and returns structured answers with citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and positions itself as the default entry point.

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 this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to step up to alternatives (ask_pipeworx_grounded for grounded single answers, deep_research for broad fan-out). It also explains how it handles breaking news, leaving little 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?

Adds context beyond annotations by explaining the candidate routing improvements, the current inactive candidate, and that it is a full working router. This complements the readOnly/idempotent hints without contradiction.

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

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

Four sentences, each delivering distinct information (what it is, current status, usage instruction, operational nature). It is slightly longer than strictly necessary but every sentence contributes 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 lacking an output schema, the description references 'same response shape' as ask_pipeworx and explains the beta behavior comprehensively. It adequately covers the tool's complexity and current state.

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 provides 100% coverage with descriptions for all six parameters (aliases for 'question'). The description adds no additional parameter-level information, so it meets the baseline but does not exceed it.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router with the same tools and response shape, and distinguishes it from the stable ask_pipeworx. It specifies the verb (route) and resource (5,529 tools), 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?

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It implies the stable version is the alternative but does not explicitly state when NOT to use this version.

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

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

Although annotations already declare readOnlyHint/openWorldHint/idempotentHint/destructiveHint, the description goes far beyond them by specifying the evidence extraction rule ('using ONLY what the tool result contains'), the full success and refusal return shapes, and the refusal reason enum values. It also discloses the extra LLM call overhead. No contradiction with the annotations exists.

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 every sentence carries critical information: purpose, routing, extraction behavior, output contract, usage scenarios, and cost comparison. It is front-loaded with the key phrase 'Hallucination-resistant answer mode' and contains no filler. This is appropriately concise for the amount of detail conveyed.

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

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

With no output schema, the description fully specifies the return format for both success and refusal cases, including the refusal_reason enum. It additionally covers behavioral constraints (evidence-only extraction), usage context (high-stakes vs. casual), and the cost tradeoff. For a single-question tool with a simple schema, this description 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?

The input schema has 100% coverage: all six parameters are documented as aliases for the natural-language question. The description adds no parameter-specific meaning beyond what the schema states, so the baseline of 3 applies. It doesn't need to compensate because the schema thoroughly describes the question field and aliases.

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 'Hallucination-resistant answer mode for high-stakes reads,' which clearly names the verb (answer), resource (Pipeworx data), and scope (high-stakes, grounded). It also explicitly contrasts with the sibling tool ask_pipeworx by describing the same routing but a different extraction-only behavior, making the tool's unique role unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also says 'prefer ask_pipeworx for casual lookups' and cites the extra LLM call cost as a tradeoff, providing a clear decision boundary between 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?

Extensive behavioral details beyond annotations: market resolution, fan-out patterns for each classifier, response shapes, resolver contract with match confidence, parent event extraction, news fallback handling, safety checks for low confidence/closed/wide markets, and cancellation rule parsing. No contradiction with readOnlyHint=true.

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 front-loaded purpose and usage, followed by detailed sections. While lengthy (~400 words), every sentence adds value for an AI agent. Minor deduction for not being more concise, but structure is logical.

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

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

Despite no output schema, the description comprehensively covers all relevant return fields (market, analysis, evidence, match confidence, parent event, news fields) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). Very complete for a complex tool.

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

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

Schema coverage is 100%, baseline 3. Description adds significant meaning: explains market parameter flexibility (slug, URL, text), depth's defaults (default thorough), and include_raw's purpose and size implications. This adds context beyond the schema's type/enum descriptions.

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

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

The description clearly states it researches Polymarket bets by pulling Pipeworx data, resolving the market, classifying, and returning evidence and comparison. Specific examples of inputs and classifiers distinguish it from siblings like polymarket_edges.

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

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

The description explicitly says 'Use for...' with three common queries, but does not provide when-not-to-use guidance or compare directly to sibling tools. The implied usage is clear but exclusions are missing.

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. Description adds specific behavioral traits: for 'company' it pulls latest 10-K data with correct fiscal year handling, for 'drug' it pulls FAERS data, results sorted by primary metric, returns citation URIs. No contradictions.

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

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

A single dense paragraph that front-loads key triggers and purpose. Each sentence adds value, but could be slightly more structured. However, 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 entity types, multiple data sources), the description covers data sources, fiscal year handling, result ordering, and citation URIs. No output schema, but return structure is described. Fairly complete.

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

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

Schema coverage is 100% with descriptions. Description adds context: for 'values' explains tickers/CIKs vs drug names, for 'type' explains what data is pulled. This adds meaning beyond the schema's enums.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs, with specific use cases listed (e.g., 'compare X and Y', 'which is bigger'), and distinguishes from siblings like entity_profile by emphasizing this replaces 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 states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear context for when to use. Doesn't explicitly exclude alternatives, but the preference statement is strong enough to guide selection.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful context about returned content (names, descriptions, Socrata ids) and links to dallas_query, enhancing transparency beyond annotations.

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

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

Two sentences with no waste. The first sentence states the action and source, the second describes the output. Front-loaded and efficient.

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

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

Given no output schema, the description explains return format (names, descriptions, resource ids) and mentions the source URL. Parameter details are covered in schema. Adequate for a search tool with good annotations.

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

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

Schema coverage is 100% with each parameter already described in the input schema (limit, query, offset, _apiKey). The description does not add new semantic meaning beyond what is in the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool searches the Dallas open-data catalogue for datasets by keyword and specifies the return fields (names, descriptions, Socrata resource ids). It distinguishes from siblings like dallas_query and dallas_recent by mentioning the resource ids are for use with dallas_query.

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

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

The description implies usage when one needs to find datasets before querying, as it returns resource ids for use with dallas_query. No explicit when-not or alternatives, but the context is sufficient given the 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 mark the tool as readOnlyHint and idempotentHint. The description adds that it runs raw SoQL, mentions the endpoint domain, and explains the optional _apiKey parameter for rate limits. This provides useful context beyond annotations without contradiction.

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

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

The description is two sentences long, front-loading the core purpose, then adding usage tips. Every sentence is informative and non-redundant. Perfectly 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?

With a full input schema (100% coverage) and no output schema, the description covers the tool's purpose, usage of parameters, and relevant siblings. It mentions the default and max limits from the schema. A minor gap: it doesn't explicitly state the return format (raw SoQL response), but that is reasonable 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the full SoQL capability and giving an example of the resource id format. It also implies which parameters are commonly used together (e.g., where, select, group, order). This goes beyond the schema descriptions.

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

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

The description explicitly states the tool runs a raw SoQL query against any Dallas open-data resource by Socrata id. It provides the resource id format (e.g., 'qv6i-rri7') and lists key SoQL clauses (where/select/group/order/limit/offset), making the purpose very clear and distinguishing it from sibling tools like dallas_datasets and dallas_recent.

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 advises using dallas_datasets to find a resource id and dallas_recent for common ones, providing alternative tools. However, it does not explicitly state when NOT to use this tool, e.g., when a simpler endpoint suffices. Still, the guidance is clear and helpful.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds that records are returned newest-first and supports SoQL where filtering, which are useful behavioral details beyond the annotations.

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

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

Description is extremely concise—five sentences with no wasted words. Front-loaded with purpose, then usage guidance, then parameter hints. 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?

Covers purpose, usage, parameter hints, and relationship to sibling tools. Without an output schema, the description could mention return fields, but for a simple recent-records tool this is sufficient.

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

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

Schema coverage is 100% with descriptions for all four parameters. Description restates dataset enum values and default limit, but does not add significant new meaning. 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?

Description clearly states it retrieves recent records from common Dallas open datasets by friendly name, avoiding the need for Socrata IDs. It distinguishes from sibling tools like dallas_query and web search by specifying its scope.

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

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

Explicitly advises preference over web search for specific queries (recent crime, 311, building permits) and directs to use dallas_query for anything else. Provides clear context for when to use this tool.

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

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

Goes well beyond the annotations: discloses account/auth requirements, paid-tier constraints, parallel routing behavior, gap[] reporting, contradiction[] output, citation resolvability conditions, semantic excerpting, and expected latency. The openWorldHint is consistent with live structured-data research, and the description clarifies it is not open-web search, so there is 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 long but front-loaded with the account requirement and each sentence adds substantive information. It could be tightened in places, but for a tool with three depth modes, multiple safety/behavioral caveats, and sibling differentiations, the length is largely justified and well structured.

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

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

There is no output schema, so the description carries the burden of explaining return values; it thoroughly does so by specifying verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop fields. It also covers timing, account tiers, depth semantics, and limitations, making it fully sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema already documents both parameters well (100% coverage), so the baseline is 3. The description adds meaningful value by clarifying that questions should be natural-language and broad/multi-part, and by noting that depth:'thorough' requires a paid plan and that standard/thorough add contradiction scanning. It does not fundamentally reshape the parameter meaning, but it adds useful operational 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 the tool performs grounded multi-source research over Pipeworx's structured data sources, decomposing questions into facets and returning a findings packet. It explicitly distinguishes itself from open-web search and from the sibling ask_pipeworx, so an agent can tell exactly what this tool does and what it is not.

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, while single lookups should use ask_pipeworx and breaking/current-news topics should prefer ask_pipeworx. It also gives account-tier requirements and depth selection guidance, making the decision boundary very 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 (readOnlyHint, idempotentHint, destructiveHint) already indicate safe read-only behavior. The description adds valuable context: returns top-N tools with names, descriptions, and full input schemas with curated examples, and states 'each result is ready to call directly, no second schema lookup needed.' 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 and well-structured, but it's relatively long with a list of domains. Every sentence adds value, but it could be slightly more concise without losing clarity.

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

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

Despite no output schema, the description fully explains the return format (names, descriptions, schemas with examples) and parameters (limit, default/max). It covers all necessary context for a discovery tool.

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

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

Schema coverage is 100% with detailed descriptions. The description adds meaning by explaining that query accepts natural language and lists aliases (task, q, description, search). Examples in the schema further clarify usage.

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

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

The description clearly states 'Find tools by describing the data or task' and lists many specific domains (SEC filings, FDA, etc.). It distinguishes from siblings like deep_research or ask_pipeworx by explicitly being a discovery tool, not a task-execution tool.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use and implicit when-not-to-use guidance, making it easy for the 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 declare readOnly=true, openWorld=true, idempotent=true, destructive=false. The description adds value by explaining the parallel call nature, data sources, soft-fail for patents, and return fields, which are not captured by 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 somewhat long but front-loaded with trigger examples and core purpose. It efficiently conveys comprehensive information without unnecessary verbosity.

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

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

No output schema exists, so the description fully takes on the burden of explaining return values (cik, filings, fundamentals, patents, news, LEI) and limitations (patents soft-fail). It provides sufficient context for the agent to understand the tool's output.

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% description coverage, so the baseline is 3. The description slightly reinforces the parameter meaning (ticker/CIK, type limited to company) but does not add new semantic depth beyond the schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and lists specific outputs. It distinguishes itself from siblings like compare_entities (different scope) and resolve_entity (name resolution).

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 trigger examples are given ('Tell me about X', 'research Acme', etc.), and it states 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' It also tells when not to use it: names not supported, use resolve_entity first.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds usage context but does not disclose additional behavioral traits beyond what annotations convey (e.g., whether deleting a nonexistent key fails silently or errors). With good annotation coverage, the description adds moderate value.

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: the first clearly states the action, the second provides usage guidance. No extraneous words, 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?

For a simple 1-parameter destructive tool with no output schema, the description covers the action, when to use, and sibling tools. It lacks details on failure behavior (e.g., missing key), but this is a minor gap 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?

Schema coverage is 100%, and the schema already describes the 'key' parameter as 'Memory key to delete'. The description does not add further semantic detail, so it meets the baseline of 3.

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

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

The description uses a specific verb ('Delete') and resource ('memory by key'), clearly stating the action. It also distinguishes itself from siblings 'remember' and 'recall' by mentioning pairing, 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 provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall', offering context on when to use this tool. However, it does not explicitly exclude alternatives or provide strict 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?

The description discloses the process (fetches page, extracts title/description/key links, outputs markdown) and confirms safety (read-only, non-destructive) aligning with annotations. No contradictions.

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

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

The description is concise, with a clear main sentence followed by a bullet list of use cases. No unnecessary words, well-structured and 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?

Given the tool's simplicity (2 params, no output schema), the description covers all needed aspects: functionality, process, output format, and use cases. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant detail beyond schema descriptions for url and max_links, offering no extra nuance.

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 for any URL, specifying the action and resource. It distinguishes from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation.

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

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

The description lists explicit use cases (indexing client sites, drafting for own project, auditing competitors). While it doesn't mention when not to use or provide direct alternatives, the context is clear and sufficient for 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 readOnly, idempotent, non-destructive hints. Description adds detail on returned fields and the include_inactive parameter, enhancing 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?

Two sentences: first states purpose and return fields, second gives usage guidance. No wasted words, 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?

With only one optional parameter and no output schema, the description provides sufficient context for correct usage.

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

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

Schema has 100% coverage for the only parameter. Description aligns with schema but adds no new meaning beyond stating active subscriptions by default.

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 verb 'list' and resource 'subscriptions', and specifies returned fields. 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?

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel.' No alternatives needed.

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

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

Annotations are all false, providing no safety clues, but the description discloses key behavioral traits: returning a `claim_token` for later lookup, being 'Rate-limited to 5 per identifier per day,' and being 'Free; doesn't count against your tool-call quota.' It also sets expectations about human review and roadmap impact. This far exceeds what annotations provide.

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

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

The description is a single dense paragraph, but every sentence contributes uniquely—purpose, usage cases, server scoping, message style, token flow, and constraints. It is front-loaded with the core purpose and expands logically. While longer than ideal, it avoids filler and justifies its length.

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

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

For a tool with no output schema, the description covers the main contexts: when to submit vs. check status, what to include, exclusions, and rate limits. The schema fully describes all parameters, including the nested `context` and `claim_token` behavior. Minor gaps remain (e.g., what happens with an account vs. without), but overall the description 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 coverage is 100%, so the baseline is 3. The description adds value by explaining the `claim_token` round-trip workflow—'Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'—and by advising on message content ('don't paste the end-user's prompt'). This enhances parameter 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly states the action (send feedback) and target (Pipeworx team). It further distinguishes from siblings by explicitly scoping to 'tools served by this Pipeworx connection' and listing use cases (bug, feature/data_gap, praise). This is a specific verb+resource with strong sibling differentiation.

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion for other MCP servers and a heuristic to identify Pipeworx tools. This is exemplary 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?

Adds value beyond annotations: source (CF analytics-engine), no PII, caching behavior (5min-1h). Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description reinforces and provides additional behavioral details.

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

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

Four sentences: first states purpose, then bulleted use cases, then technical provenance and caching. Every sentence carries essential information, no redundancy.

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

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

Given simple tool (1 optional param, no output schema, strong annotations), description covers purpose, usage, behavioral traits, and parameter semantics completely. No gaps.

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

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

Parameter 'window' is explained with semantic meaning: shorter windows for what's hot, longer for steady-state demand. Schema only provides enum values and default; description adds interpretative context.

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

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

Description clearly states it returns top tools, packs, and call volume over windows. Specific verb 'Returns' and resource 'top tools, top packs, total call volume' distinguishes from siblings like discover_tools or ask_pipeworx.

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

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

Explicitly lists three use cases (discovering hot data, confirming canonical tool, aligning use case). Lacks explicit when-not-to-use or alternative names, but context is clear.

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

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

The description goes well beyond the annotations (which already indicate readOnly, idempotent, openWorld). It details the internal logic: monotonicity violations, partition-sum checks, Jaccard similarity threshold (≥0.30), placeholder filtering, fill check against CLOB depth. It also describes the response structure and the conditions under which signals are null or untradeable. 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 relatively long but every sentence contributes meaning. It is well-structured with clear sections (modes, semantic anchor, partition filter, response, fill check). It is front-loaded with the purpose and mode options. Could potentially be slightly more concise, but the density of useful information justifies the length.

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

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

Given the complexity of the tool (multiple modes, multiple checks, edge cases) and the absence of an output schema, the description is remarkably complete. It explains the return fields, the fill check outcome, the placeholder filter, and when signals are null. It also covers the semantic anchor and the conditions for cross-event pairing. No additional context seems missing.

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

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

The input schema already has detailed descriptions for event and topic. The description adds value by providing concrete examples (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), clarifying that no args triggers a trending scan, and giving usage recommendations. However, the schema descriptions are already quite strong, so the extra value is moderate.

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 core function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It immediately distinguishes three modes (trending, event, topic) and explains what each does. It implicitly distinguishes from sibling tools like polymarket_edges by focusing on arbitrage rather than general edges.

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

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

The description explicitly tells the user when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event mode for specific markets, explains cross-event mode catches patterns, and advises against trading when realizable_edge_pp ≤ 0. It also references the sibling tool polymarket_fill_risk for custom sizing.

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

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

The description goes far beyond annotations by detailing caching (1h KV), model methodologies, slippage handling, edge calculation, diagnostics for empty segments, and limitations of Fed signals. It provides rich behavioral context that helps an agent understand what the tool does internally, complementing the readOnlyHint and idempotentHint 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, but it is verbose and includes implementation details (e.g., specific alpha values, Kelly caps) that may be excessive for an agent's invocation decision. The first sentence is front-loaded and clear, but the overall length could be trimmed for better conciseness.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure (by_segment, diagnostics, fields like edge_pp_net, kelly_fraction) and covers edge cases (empty segments, Fed note, caching). It provides complete guidance for an agent to understand what to expect, including why segments might be empty.

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 context on parameter interactions (e.g., min_kelly vs min_partition_leg_kelly) and tradeable-edge knobs, but most parameter details are already in the schema. No significant new meaning is added beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for 'what should I bet on today' and distinguishes itself from sibling tools by focusing on opportunity discovery without paging through hundreds of markets.

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 extensive usage context, including the intended use case ('what should I bet on today'), the three segments with model families, and how to interpret results. It implies when to use (discovery) but does not explicitly state alternatives or when not to use, though sibling tools like polymarket_arbitrage and polymarket_edge_tracker suggest different scopes.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds details about what the response contains (tracked, expired, snapshot_dates) and limitations (cache-miss gaps, no intraday data). 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 detailed but well-structured: starts with a clear purpose, then specifies arguments, response fields, and limits. Every sentence adds value, though slightly verbose for a tool with only two parameters.

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

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

Given the absence of an output schema and the tool's complexity, the description adequately covers purpose, parameters, response structure, and operational limits. It provides enough context for an agent to decide and invoke correctly.

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

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

Both parameters are fully described in the schema (100% coverage). The description adds context: days default 14, clamp 2-30; window meaning 'snapshot family' with examples. This enriches 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 provides 'edge persistence and decay telemetry' from daily snapshots, specifically answering 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis rather than raw edge discovery.

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

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

The description explains the use case (distinguishing fresh wide edges from aged ones) and includes a LIMITS section with constraints (60-day TTL, decay from daily closes). However, it does not explicitly exclude scenarios or name alternative tools for similar tasks.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Description adds operational behavior: walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, verdict, and explains forced_directional_risk. This goes beyond the safety profile provided by annotations.

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

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

Description is thorough and well-structured with capital letters for modes, but is lengthy. Every sentence adds value, but density could be slightly reduced for faster parsing. However, given complexity, this is appropriate.

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

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

No output schema exists, so description fully explains return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). Also covers real-world risk of partial fill leading to unhedged positions.

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 significant meaning: explains mode selection (market vs event), side auto-detection for baskets, size_usd interpretation as settlement notional for baskets, and default values. This greatly aids correct parameter usage.

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

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

Description clearly states 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) and says 'USE THIS before acting on' them, providing strong differentiation.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns about partial basket fills converting an arb into an unhedged directional position. Does not explicitly list when not to use, but context implies for small trades or non-arb signals.

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 and idempotentHint. The description adds beyond that: it details compatibility warnings, temporal alignment, and reasons for zero matches (e.g., skipped cross types). 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 comprehensive and well-structured, with clear sections for modes, response fields, and safety warnings. However, it is somewhat verbose; a few sentences could be trimmed without losing essential information.

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

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

Despite lacking an output schema, the description fully documents the response structure including safety fields, temporal alignment, and counters. It covers all necessary details for an agent to understand the output.

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 significant meaning: explains the two modes, lists valid topics, and clarifies that explicit parameters override topic mapping. This goes 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 it computes cross-venue spreads between Kalshi and Polymarket for the same question. It distinguishes between two modes and explains when spreads are meaningful, differentiating it from siblings like polymarket_arbitrage.

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

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

The description explicitly says when to use this tool (to find cross-venue spreads) and when not, using safety fields like compatibility_warning and temporal_alignment. It notes that pre-mapped topics are not necessarily tradeable, providing clear usage context.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint; the description adds scoping details ('Scoped to your identifier') and pairing with remember/forget, providing behavioral context beyond annotations.

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

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

Two sentences covering action, usage, scoping, and pairing. Could be slightly more concise but front-loads key information 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 the single optional parameter, full schema coverage, and annotations, the description completely covers purpose, usage, scoping, and tool relationships without needing output schema details.

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

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

Schema has 100% coverage (parameter 'key' is described as 'omit to list all keys'). Description repeats this but does not add new meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes from siblings remember and forget by naming them and explaining the role.

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 when to use: 'to look up context the agent stored earlier' with examples (ticker, address, research notes). It mentions scoping and pairing but does not explicitly state when not to use or list alternatives.

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

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

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint. Description adds context about mark_read affecting future calls ('so the next call only shows newer ones') and polling behavior, which goes beyond annotation metadata.

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 no redundant words. Purpose is front-loaded, followed by essential details. 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?

For a read-only tool with full schema coverage and no output schema, the description explains return fields, filter usage, and alternative access. Covers all user-facing aspects completely.

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

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

Schema coverage is 100%, baseline 3. Description adds semantics for type (example 'sec_8k'), since (ISO timestamp), and mark_read (flag to mark as read). Does not mention limit or unread_only, but overall adds value beyond the schema.

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

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

The description clearly states 'Pull fired events from your subscription feed' and specifies key fields returned (source, citation_uri, raw event payload). It distinguishes itself from siblings like list_subscriptions by focusing on event retrieval from a persisted feed.

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 usage guidance: polling works fine, alternative GET endpoint for scripts, and examples of filters (e.g., 'sec_8k'). Lacks explicit when-not-to-use or comparison with siblings, but context is sufficient for an agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds detailed behavioral context: the multi-source fan-out, fallback logic, soft-fail for USPTO, and the accepted date formats. 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 but informative, using examples and a clear structure. It front-loads the purpose and includes all necessary details without excess verbiage. Minor point: it could be slightly more structured with sections, but it's very effective.

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

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

Despite no output schema, the description covers return format details (structured changes grouped by source, total_changes count, citation URIs). It also addresses edge cases like fallbacks and soft-failures. Highly complete for the tool's complexity.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining the 'type' enum restriction, providing examples for 'value' and 'since', and clarifying relative shorthand usage. This goes beyond the schema's descriptions.

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

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

The description uses specific verbs like 'change feed' and specifies the resources (SEC EDGAR, GDELT/GNews, USPTO). It clearly distinguishes from the sibling tool 'entity_profile' by stating when to use each. This meets the criteria for a 5.

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 explains the tool's purpose with example queries and provides a clear alternative: 'Use entity_profile instead when you want the static profile...'. It also describes the fallback behavior between data sources, giving comprehensive 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?

Adds useful context beyond annotations: scoping by identifier, persistence (24h for anonymous). Does not explicitly mention overwrite behavior or idempotency, but addresses core storage semantics.

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

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

Three sentences, front-loaded with purpose, no unnecessary words. Efficiently delivers all key information.

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

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

For a simple key-value store with no output schema, the description covers purpose, usage, persistence, and pairing with siblings. Complete and clear.

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

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

Schema coverage is 100%; description adds naming conventions (e.g., 'subject_property') and clarifies value is free text, providing richer semantics than schema alone.

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

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

The description clearly states the tool saves data for reuse, with specific examples (ticker, address, preference). It distinguishes from siblings by naming recall and forget as paired tools.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and how to pair with recall/forget, including persistence details for authenticated vs anonymous sessions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond those annotations: it explains that the tool cascades through multiple lookup endpoints, that LEI/FIGI enrichment degrades gracefully if upstream sources are unavailable, that identifiers are labeled with their source, and that unresolved identifiers are explicitly listed under 'unresolved' rather than omitted. These are valuable operational details not visible in the schema or annotations.

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

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

The description is dense and somewhat long, but every sentence contributes value: examples, supported types, source coverage, graceful degradation, and output conventions. The opening example list is effective at capturing intent, and later details are necessary for correct use. It could be slightly better structured with clearer separation, but it remains concise for the amount of behavior it conveys.

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

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

Given the complexity of the tool (multiple source systems, two entity types, fallback behavior, explicit unresolved handling) and the absence of an output schema, the description goes beyond minimal viability. It explains return contents (identifiers with source labels, unresolved list, ownership data, RxCUI citation), input acceptance, and failure modes. This is sufficient for an agent to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, with both parameters (type and value) fully described, including enums and examples. The description reinforces the accepted input formats ('ticker, CIK, or company name' for company; 'brand or generic name' for drug) but does not add new meaning beyond what the schema already provides. The extra context in the description mostly concerns output behavior, not parameter semantics, 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 opens with concrete example queries and a clear verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly differentiates this from sibling tools by stating 'Use FIRST whenever you have a name but need an ID' and by describing the two supported entity types. This makes the tool's purpose unmistakable and distinct.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also specifies supported types and acceptable inputs for each. It does not name alternative sibling tools, but it implies the tool is a prerequisite to other tools ('identifiers other tools require as input') and notes it replaces '2-3 manual lookups.' This is clear context, though it lacks explicit 'when not to use' 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?

Description adds context beyond annotations: performs multiple probes, ranks by score, treats first entity as subject. All annotations (readOnly, openWorld, etc.) are consistent.

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 purpose, no fluff. Every sentence contributes meaning.

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

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

Despite no output schema, description specifies return fields (score, confidence, signal density). Covers all parameter roles and behavior sufficiently for an agent.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by clarifying the role of the first entity in 'entities' and the purpose of 'context'. Does not repeat schema descriptions verbatim.

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 'Compare AI visibility across multiple entities side-by-side,' specifying the verb, resource, and output. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (likely different 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?

Provides explicit use case ('competitive AI-marketing audits') and an example question. Implicitly distinguishes from single-entity tool, but lacks explicit when-not-to-use or alternatives.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds critical behavioral context: partial failures degrade gracefully, specific timeout behavior for bundlephobia, and which fields indicate failure (sources_failed). No contradiction with annotations.

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

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

The description is a single cohesive paragraph that efficiently covers purpose, usage, ecosystem, and graceful degradation. It is informative but could be slightly more structured; still, every sentence adds value.

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

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

Despite lacking an output schema, the description explains the return format (summary block, per-advisory detail, links, alternative versions) and covers all important aspects: composite nature, external services, latency, failures, and ecosystem scope. Complete for a tool of this complexity.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds little beyond the schema for parameters, mentioning that version defaults to latest. Baseline 3 is appropriate as schema already carries the meaning.

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

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

The description clearly states it is a composite check for npm packages, fans out to deps.dev and bundlephobia, and explicitly distinguishes from siblings by noting the NPM-only scope and alternative for other ecosystems.

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

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

Provides explicit when to use ('is X safe/popular/small', 'what does adding lodash cost'), warns about bundlephobia latency (5-30s first measurement), and specifies ecosystem boundaries (NPM only; others use deps.dev:version directly).

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses the embedding model (BGE-base-en), search method (cosine over 500-char overlapping windows), character cap (200K chars with truncation flag), and that passages include offsets for verification.

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

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

The description is a single dense paragraph that efficiently conveys purpose, usage, behavioral details, and limitations. It is front-loaded with the key verb and resource. Some minor redundancy (e.g., mentions cap twice) prevents a 5.

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

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

For a 3-parameter tool without output schema, the description fully covers intents, limitations (truncation), return format (passages with offsets and scores), and pairing with siblings. It's self-contained.

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 example queries and slightly elaborates on the text parameter cap, but mostly restates schema info.

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

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

The description explicitly states 'Semantic search INSIDE a fetched record' and provides concrete examples like SEC 10-K body, article, tool result. It distinguishes from the sibling ask_pipeworx_grounded by explaining the pairing pattern.

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: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also suggests pairing with ask_pipeworx_grounded as an alternative workflow.

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

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

Annotations provide basic hints (readOnlyHint false, idempotentHint true, destructiveHint false). Description adds context about persistence, delivery channel limits (10 SMS/day), webhook signing, and auto-disable after failures. This supplements annotations well without contradiction.

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

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

Description is information-dense but well-structured: purpose, prerequisite, types with examples, delivery channels. Front-loaded with core action. Could be slightly more concise, but every sentence adds necessary detail.

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

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

Given 3 parameters (with nested objects), no output schema, and complexity of subscription types and delivery channels, the description covers prerequisites, type-specific params, delivery options, return value, and important behavioral notes (webhook secret once, auto-disable). No major gaps.

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

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

Schema has 100% coverage, so baseline is 3. Description enriches this with concrete examples for each type (e.g., 'sec_8k' items codes, 'polymarket_edge' topic) and detailed delivery channel behavior (webhook HMAC signing). Adds value 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?

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource combination that distinguishes it from sibling tools like list_subscriptions or unsubscribe.

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

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

Description mentions prerequisite (requires Pipeworx OAuth account) and lists supported types with examples, guiding type selection. However, it does not explicitly contrast with sibling tools or state when to avoid this tool (e.g., for listing existing subscriptions).

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 behavioral context beyond these: it draws from a live catalog and returns category-bucketed examples, which is valuable for understanding the tool's operation.

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 with initial alternative phrasings and a parenthetical list of categories. It is front-loaded with the core purpose and usage guidance. Minor redundancy in listing categories both in text and examples, but overall efficient.

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

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

Despite lacking an output schema, the description fully explains the return structure: category-bucketed example questions with tool and argument shapes. It covers all necessary context for a first-use tool, including how to focus and alternative use cases.

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

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

Schema coverage is 100% with a single parameter. The description adds the exact allowed values (finance, pharma, etc.) and explains the effect of omitting or providing the topic, surpassing what the schema provides.

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

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

The description clearly states the tool serves as an onboarding entry point, returning category-bucketed example questions with associated tools and arguments. It distinguishes itself from siblings like ask_pipeworx and discover_tools by specifying its role in helping users discover what to ask.

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

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

Explicit guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also explains how to use the optional topic parameter to focus results, and notes that calling without arguments gives a full spread.

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 mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). Description adds key context: row is deactivated not deleted, preserving historical events. 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 succinct sentences: action + constraints/behavior. No wasted words, front-loaded with key 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?

Simple tool (1 param, no output schema). Description covers purpose, ownership, side effects, and references sibling tool for history. Sufficient for agent to use correctly.

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

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

Only parameter 'id' is fully described in schema (100% coverage). Description repeats that id comes from 'subscribe', adding no new semantics beyond schema. Baseline 3 applies.

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

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

Description clearly states 'Cancel a subscription by id.' with specific verb (cancel) and resource (subscription), distinguishing it 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?

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions') and explains effect (deactivation not deletion), guiding when to use and directing to 'recent_alerts' for historical data.

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

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

The annotations already mark the tool as read-only and idempotent, so the description goes beyond by disclosing the verdict values, the meaning of 'could_not_verify' (a failed check, not evidence), the distinction between 'unsupported' and 'could_not_verify', the routing to SEC EDGAR vs. grounded pipeline, and the presence of verification_error metadata. This is rich, non-redundant behavioral context.

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

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

The description is dense but every sentence contributes: usage phrasings, routing rules, return value summary, caller warnings, and an efficiency note. It is not bloated and avoids tautology, with the most critical information (purpose and routing) 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?

For a 2-parameter tool with no output schema, this description is exceptionally complete: it covers input expectations, routing logic, return verdicts, error semantics, and caller responsibilities. Nothing is left ambiguous 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%, but the description adds meaningful parameter nuance: tolerance_pct overrides the claim's implied tolerance, is capped at 5 by default, and can be set to 1–2 for hallucination detection. The claim parameter is illustrated with realistic examples, enhancing the schema's brief 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 identifies the tool as a natural-language claim verification service, opening with explicit phrasings like 'Is it true that…' and 'fact check'. It names the verb (verify) and resource (factual claims against authoritative sources), and distinguishes itself from sibling tools by describing the dual financial/grounded routing paths.

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

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

It gives an explicit usage directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains that it replaces 4–6 sequential calls, implying efficiency benefits. However, it does not name alternative tools for non-claim tasks or explicitly state when not to use it.

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