Data Denver

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

Adds details beyond annotations: cost implications (free vs. Anthropic BYO), return format (score, confidence, signals, raw_response, combined view). No contradiction with readOnlyHint=true or other 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?

Single paragraph with key information front-loaded (action, resource, scoring). Efficient but could benefit from slight restructuring (e.g., separating return format). No wasted sentences.

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 fully explains return values and structure. Covers prerequisites (API key), default behavior, and use cases. Complete for a probing tool with simple input parameters.

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

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

Schema coverage is 100%, but description adds value by explaining default model behavior for 'models' parameter and how '_apiKey' is passed through. Clarifies context parameter usage for disambiguation.

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

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

Description uses specific verb 'probe' and resource 'LLMs' with scoring of visibility. Clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' and 'ask_pipeworx' by focusing on brand visibility across models.

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

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

States use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and gives context on default model vs. Anthropic with key. Lacks explicit when-not-to-use but provides clear situational guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context about routing to sub-tools, filling arguments, returning citation URIs, and being a fast single call. This goes beyond the structured hints 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 long but front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH') and organized with examples and explicit alternatives. Every sentence adds useful information, though it could be tightened slightly without losing value.

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

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

Given no output schema, the description sufficiently covers return behavior (structured answer with citations), usage scope, and alternatives. It provides enough context for an agent to decide when to invoke this tool and what to expect.

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

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

Schema coverage is 100%: the schema already documents all aliases (q, text, input, query, prompt, question) and states that question accepts natural language. The description provides usage examples but doesn't add parameter-level detail beyond what the schema already covers, so it meets the baseline.

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

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

The description clearly states the tool's purpose: it routes questions to the appropriate tool among 5,462 verified sources and returns structured answers with pipeworx:// citation URIs. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making it unambiguous what this tool does.

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

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

The description explicitly says to prefer this tool over web search, provides trigger phrases ('what is', 'look up', 'find', etc.), and gives step-up guidance: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad multi-part questions. It even notes that breaking news is handled internally.

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

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

Beyond the read-only/idempotent annotations, the description discloses the experimental live nature, the current state (no active candidate), and that it is a full working router with no fallback. This adds meaningful behavioral context about potential variability and parity.

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 convey all key information: beta status, parity with stable, active candidate state, usage directive, and experimental purpose. Each sentence earns its place with no redundancy.

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

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

Given the simple input (one question with aliases), strong annotations, and no output schema, the description covers the tool's purpose, current behavior, and usage context comprehensively. It leaves no critical gaps for invocation.

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

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

All six parameters are documented in the schema as aliases for the single required 'question' field with 100% coverage. The description mentions 'same arguments' as ask_pipeworx but does not add further parameter semantics; the schema already provides full 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 identifies the tool as a beta variant of ask_pipeworx, a universal router for natural-language questions, and distinguishes it by its experimental routing improvements. It specifies the exact scope (same 5,462 tools, same arguments, same response shape) and differentiates it from the stable sibling.

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

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

The description explicitly states to use it exactly like ask_pipeworx when wanting the newest routing, and notes that results are compared against the stable router to decide merges. This provides clear context for when to choose this beta over the stable version.

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

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

The description goes well beyond the annotations by detailing the exact success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and enumerated refusal reasons. It also discloses the additional LLM call cost. These are behavioral traits not visible in the schema or annotations, and they align with the readOnlyHint/openWorldHint.

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 earns its place: purpose, mechanism, output format, usage guidance, and cost trade-off. It is well-structured and front-loaded with the most critical information ('Hallucination-resistant...'), with no redundant filler.

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

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

Despite no output schema, the description fully specifies both success and refusal return structures, which is essential for an agent to interpret results. It also covers cost implications, making it complete for the complexity of a grounded multi-tool answer mode.

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

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

Schema coverage is 100% with all aliases documented. The description does not add any parameter-specific semantics beyond what the schema provides, but it doesn't need to. Given the high schema coverage, a baseline 3 is appropriate.

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

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

The description opens with a specific, high-signal phrase: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly states the tool's function (answering questions grounded in fetched data) and distinguishes it from the sibling ask_pipeworx by emphasizing extraction-only-from-tool-result behavior. This is a specific verb+resource with clear 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?

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' This directly tells the agent when to use this tool vs. the alternative, and even highlights the trade-off (extra LLM call). No ambiguity.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing market resolution, classifier fan-out, response shapes, resolver contract, parent event extraction, news fallback, safety short-circuits, wide-spread handling, and cancellation rule parsing.

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 (~500 words) but well-structured with bold section headers (e.g., CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) and front-loaded core purpose. While comprehensive, some redundancy could be trimmed for an AI agent.

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

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

Given the tool's complexity (multiple classifiers, fan-out sources, detailed response fields, error handling), the description is fully complete. It covers all response shapes, edge cases (low confidence, closed markets, wide spreads), and cancellation rules—essential since no output schema exists.

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

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

Schema coverage is 100%, and the description adds significant value: it explains depth options ('quick = 2-3 evidence sources'), market parameter types (slug, URL, text), and include_raw summary vs full payload, which is not in the schema descriptions.

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

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

The description clearly states the verb ('Research') and resource ('Polymarket bet') and method ('pulling Pipeworx data'), and distinguishes from sibling tools like 'ask_pipeworx' by emphasizing the fan-out and classification logic.

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 use cases are given ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), though no direct alternative tools are mentioned. The context from sibling names implies when not to use this tool.

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

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

Annotations indicate safe read-only, idempotent behavior. The description adds meaningful context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/Trials for drugs), fiscal year handling, and result sorting, going beyond annotations.

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

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

The description is dense but well-organized, front-loading key purpose and usage. Every sentence adds value, though it's a single paragraph without explicit structure.

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

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

Given no output schema, description adequately explains return data (paired data + citation URIs) and data freshness. Rich annotations compensate for any gaps, but a note on auth or rate limits could improve completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description clarifies enum values and array constraints but doesn't add format details beyond schema.

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

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

The description explicitly states the tool compares 2-5 companies or drugs side-by-side in one parallel call, with example queries and clear distinction from 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?

The description explicitly instructs to prefer this over sequential lookups and details when to use for company vs drug types, providing clear guidance on appropriate contexts.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive; the description adds substantial behavioral detail beyond that: account/paid-plan requirements, explicit gaps[] for unanswered facets, 'never invented' grounding, timing expectations (15-60s, ~90s for thorough), citation fetchability, semantic excerpting, and hop/contradictions fields. 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 long but well-organized and front-loaded with the critical account requirement and primary use case. Each section adds useful operational detail (account, alternatives, examples, depth semantics, output features, timing). While dense, the complexity of the tool justifies the length; however, some depth explanation duplicates the schema description.

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

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

For a complex tool with no output schema, the description covers the return format (findings packet, verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field), prerequisites, timing, and clear behavioral boundaries. It equips an agent to select and call the tool appropriately for a wide range of research questions.

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 meaningful descriptions for both question and depth. The description enriches parameter understanding by explaining depth levels in more context (e.g., gap recovery, iterative chasing, contradictions scan) and providing example question phrasings for the question parameter. Slight redundancy with schema but adds contextual value.

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

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

The description uses a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' with detailed mechanics (decomposes into facets, routes to 5,462 tools in parallel, returns a findings packet). It clearly distinguishes itself from sibling tools like ask_pipeworx by noting this is 'NOT open-web search' and stating it is for broad/multi-part questions.

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

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

Explicit guidance is provided: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also specifies an account prerequisite and gives the alternative if not signed in: 'If you are not signed in, use ask_pipeworx instead'.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's addition of 'for discovery' and the return of layer id+name adds moderate behavioral context. No contradictions, but no extra details on auth or rate limits.

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

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

Two sentences, no extraneous words. Front-loaded with the core purpose and then details on usage. 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 simple discovery tool with one optional parameter and no output schema, the description covers input options, output purpose, and relationship to denver_query. 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 description coverage is 100%, and the description largely mirrors the schema's parameter description (e.g., short name, full path, omit to list services). The examples in the schema add value, but the description does not significantly augment the schema.

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

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

The description clearly states the verb 'List' and the resource 'layers of a Denver ArcGIS service (for discovery)'. It specifies how to use short names or full paths and what happens when 'service' is omitted, distinguishing it from sibling tools like denver_query and denver_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 explains when to omit the service parameter to list known services, and how to pass short names or full paths. It notes the output is for use with denver_query, providing context for tool chaining. However, it does not explicitly state when not to use this tool or mention alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds: 'Epoch dates are converted to ISO.' This is a behavioral trait beyond 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 two sentences: the first defines core purpose, the second adds usage guidance and a key detail. Every sentence is essential and front-loaded. No redundant words.

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

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

The tool has 6 parameters (2 required), no output schema. The description explains the query capability, links to related tools, and mentions date conversion. It covers the main use case. Minor gaps: no mention of error handling or response structure, but these are less critical for a query tool with clear parameter semantics.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description adds value by providing examples (e.g., 'service: crime' as a short name), defaults (where: '1=1', limit: 100, max: 2000), and format guidance for order_by. This enriches understanding beyond the raw schema.

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

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

The description states: 'Query any Denver ArcGIS layer by service path + layer id.' It specifies the verb (query), resource (Denver ArcGIS layer), and scope (by service path and layer id). It distinguishes itself from sibling tools like denver_layers and denver_recent by focusing on query execution.

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: 'Use denver_layers to find a service/layer, or denver_recent for the common ones.' This provides clear context and alternatives. It does not explicitly state when not to use the tool, but the guidance is strong.

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?

Describes return order (newest-first) and date conversion (ArcGIS epoch to ISO), adding context beyond 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?

Three sentences, each packed with essential information—no wasted words, clear and efficient structure.

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 dataset naming; references siblings for deeper queries. Lacks error/rate-limit details but annotations cover safety. Adequate for a simple 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%; description adds minor context (date conversion, filtering hint) but doesn't significantly enhance param understanding beyond the schema definitions.

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

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

The description clearly states it returns recent records from Denver open data, specifies the source (ArcGIS), and distinguishes from web search and sibling tools like denver_layers and denver_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?

Explicitly says 'PREFER OVER WEB SEARCH for recent crime in Denver', and provides guidance on using the where parameter for filtering, with references to sibling tools for other layers.

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 and idempotentHint. Description adds that it returns top-N relevant tools with full schemas and curated examples, ready to call. Describes behavior 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?

Approximately 5 sentences, well-structured: purpose first, then examples, return format, and usage advice. Every sentence adds value; no fluff.

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

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

Given no output schema and a discovery use case, description covers purpose, input, and return format (names, descriptions, schemas). Could briefly mention ranking criterion, but sufficient for selection.

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

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

Schema coverage is 100%. Description adds meaning by clarifying that query accepts multiple aliases (task, q, description, search) and provides natural language examples. Adds value beyond raw schema fields.

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

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

Description clearly states the tool's purpose: 'Find tools by describing the data or task.' Lists diverse examples and emphasizes returning full schemas ready to call. Distinct from siblings by specifying it's the first call to explore the option set.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context and alternative guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds further behavioral traits: parallel fan-out, soft-fail for patents, fallback logic for news, and specific return fields. No contradiction.

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

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

The description is front-loaded with examples, then bullets data sources and return structure. Every sentence adds value: usage guidance, parameter constraints, source details. Slightly long but 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 fully compensates by listing all return fields (CIK, filings with URIs, fundamentals with sorting, patents status, news fallback, LEI). Complete for a profile tool.

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

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

Schema coverage is 100% so baseline is 3. The description adds meaning by explaining 'type' is limited to 'company', 'value' is ticker or CIK, explicitly banning names. This goes beyond the schema's enum and type 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 'full cross-source profile' and 'research', lists multiple example user intents, and distinguishes itself from sibling tools by stating preference over chaining single-pack lookups. It clearly answers 'what does this tool do?' with concrete resource (US public company) and 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 states when to use ('holistic view') and when not to use ('single-pack lookups'). Mentions alternatives (resolve_entity for names). Provides constraints: ticker or CIK only, not names. No ambiguity.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's 'Delete' verb is consistent. The description adds context about clearing sensitive data, but no additional behavioral traits beyond what annotations provide. No contradiction.

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

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

Three sentences with no wasted words: first sentence states the action, second provides usage context, third mentions related tools. Efficient 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?

For a simple tool with one parameter, the description covers purpose, usage, and relationships. No output schema needed. Complete enough for an agent to select 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?

Schema coverage is 100% with one parameter 'key' described as 'Memory key to delete'. The description ('by key') adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly stating the tool's function. It also distinguishes itself from sibling tools like 'remember' and 'recall' in the last sentence.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Mentions pairing with 'remember' and 'recall'. Lacks explicit when-not cases, but still offers clear guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds that it fetches the page, extracts title/description/key links, and outputs standard markdown. It also says the output is a single text blob for site-root/llms.txt, which is useful context beyond annotations.

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

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

The description is concise: two sentences plus a list of use cases. Every sentence adds value, and the main action is front-loaded. No redundant information.

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

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

Given the tool has only 2 parameters, full schema coverage, and rich annotations, the description adequately explains the output format and what is extracted. No gaps remain for the agent to understand the tool's behavior.

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

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

Schema description coverage is 100% with both parameters documented. The description does not add significant meaning beyond the schema; it mentions URL and max_links but the schema already includes defaults and limits. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Generate', the resource 'llms.txt file', and the scope 'for any URL'. It explains the process (fetch, extract, emit) and distinguishes itself from sibling tools which have different purposes.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting llms.txt for own project, or auditing competitor. It does not mention when not to use or alternatives, but the use cases are clear and relevant.

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, destructiveHint=false, so description's mention of return fields adds marginal value. No contradictions.

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

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

Two sentences, efficient and front-loaded with purpose. Every word earns its place.

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

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

Given the tool's simplicity, single optional parameter, and lack of output schema, the description fully covers its behavior and return fields.

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

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

Schema coverage is 100% (one boolean parameter), and description does not add meaning beyond the schema. Baseline of 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' and enumerates returned fields (id, type, params, created_at, last_fired_at, fire_count). 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 says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context but lacks explicit when-not-to-use.

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

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

Annotations are all false, so the description carries the full burden of behavioral disclosure. It does an excellent job by revealing rate limits ('Rate-limited to 5 per identifier per day'), quota impact ('Free; doesn't count against your tool-call quota'), and downstream effects ('team reads digests daily and signal directly affects roadmap'). It also adds content constraints like 'don't paste the end-user's prompt.'

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

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

The description is front-loaded with the core purpose and then flows logically through usage, exclusions, content guidance, and behavioral constraints. Every sentence provides useful information, though at roughly 120 words it is longer than strictly necessary. The structure is clear and well-organized.

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

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

For a feedback submission tool with a rich schema and no output schema, the description is fully complete. It covers the tool's purpose, exact scenarios for use, when not to use it, what to include in the message, rate limits, and quota treatment. There is nothing meaningful missing for an agent to use it correctly.

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

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

The schema provides 100% parameter coverage with detailed descriptions for type, context, and message. The description adds meaningful value beyond the schema by advising 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' and reinforcing the type categories. This goes beyond the baseline 3 for full schema coverage.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a specific verb-plus-resource that clearly states the tool's purpose. It distinguishes itself from sibling tools like ask_pipeworx by framing this as feedback about the tooling itself, not a question or data 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?

Explicit when-to-use guidance is provided: '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 gives a clear when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead.' This fully covers alternatives and exclusions.

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

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

Adds context beyond annotations: describes data source (CF analytics-engine), privacy (no PII), caching (5min-1h), and self-aggregating nature. Annotations already declare readOnly, openWorld, idempotent, non-destructive; description enriches behavioral understanding.

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 plus bullet points. Front-loaded with core function, then use cases, then metadata. No extraneous words; every sentence adds value.

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

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

Covers what is returned (top tools, top packs, total call volume), caching, and privacy. Lacks explicit output schema, but for a simple read tool the description 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?

The schema has one parameter with enum and description. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose values appropriately.

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, top packs, and total call volume over recent windows. Distinguishes itself from sibling tools like discover_tools and ask_pipeworx by focusing on trending usage data.

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

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

Lists three specific use cases (discovering hot data sources, confirming canonical tool, checking alignment). However, does not explicitly state when not to use this tool 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) establish safety and idempotency. The description enriches this with detailed behavior: semantic similarity thresholds, placeholder filtering, partition sum checks, and fill check logic. No contradictions exist; the description adds value beyond the annotations.

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

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

The description is fairly long but well-structured, starting with a summary, then breaking into mode details, filters, response format, and fill check. While comprehensive, a slight reduction (e.g., moving some details to a separate note) could improve conciseness without losing critical information.

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

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

Given no output schema, the description thoroughly explains the response structure, including fields like gap_pp, suggested_trade, reasoning, and partition_check in event mode. It covers what happens with each input mode, edge cases (e.g., placeholder filtering), and even warns when the trade is not realizable. The tool's interaction with a sibling tool (polymarket_fill_risk) is noted, ensuring the agent has full context.

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

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

Although the input schema covers both parameters 100%, the description adds significant meaning: it explains the purpose of each parameter, provides real-world usage examples, and details how each mode operates. This helps the agent understand the semantic impact of choosing event vs. topic beyond the schema descriptions.

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

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

The description clearly states the verb 'Find arbitrage opportunities', the resource 'on Polymarket', and the methods 'via monotonicity violations + partition-sum checks'. It distinguishes three distinct modes (no args, event, topic) and uses specific examples, making the purpose unambiguous and well-differentiated from sibling tools.

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

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

Explicit guidance is provided for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It includes usage examples, conditions for when not to trade, and references a sibling tool for custom sizing, giving clear when-to-use and when-not-to-use advice.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: data sources (FRED log-returns, GDELT ratio), calculation details (favorite-longshot bias correction, Kelly caps), response structure with diagnostics, and caching behavior. 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 thorough but long (approx. 300 words). It front-loads the purpose but could be more concise. The structure uses paragraphs and some inline lists, making it adequate for an agent but slightly verbose.

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

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

Despite no output schema, the description comprehensively covers the response structure (by_segment segments, fed_candidates, _diagnostics), per-opportunity fields, caching, and why segments may be empty. This makes the tool well-understood without additional documentation.

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 role of parameters like min_partition_leg_kelly in detail, clarifying how tradeable-edge knobs filter opportunities beyond the schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and specifies it is built for 'what should I bet on today' for agents. It distinguishes from sibling tools by detailing unique model families and tradeable-edge knobs.

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 tool helps agents discover opportunities without paging through hundreds of markets, and provides context for when to use tradeable-edge filters. It does not explicitly state when not to use, but the sibling list implies alternatives exist, and the description covers limitations like Fed data unreliability.

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

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

Description adds behavioral traits beyond annotations: response structure (tracked, expired, snapshot_dates), edge_pp_net sign, decay computation (daily closes, not intraday), and bounds (60-day TTL, snapshot enable time). No contradiction with annotations.

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

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

Description is dense but well-structured, starting with purpose, then response format, then limits. Every sentence adds value, though slightly longer than necessary.

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, description fully explains return values and their meaning, including edge_pp_net sign, trend classification, and date gaps. Covers limits and assumptions thoroughly.

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

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

Schema has 100% coverage; description adds default values and clarifies semantics like 'snapshot family' for window. Provides more context 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 provides edge persistence and decay telemetry from daily snapshots, distinguishing it from sibling tools like polymarket_edges. It answers a specific question: how long an edge has existed and whether it's shrinking, with concrete examples.

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

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

The description implies when to use the tool (for historical trend analysis) and contrasts fresh vs. old edges, but does not explicitly state when not to use or name 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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it checks order book depth, walks the ladder, returns verdicts (clean|degraded|cannot_fill), and warns about forced directional risk. No contradiction with annotations.

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

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

The description is long but well-structured with section headers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). It front-loads the purpose and every sentence adds value. Minor redundancy could be trimmed, but the density 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?

No output schema exists, so the description details many return fields (top_of_book, vwap_fill_price, slippage_pp, etc.). It covers both modes, explains edge cases (thin books, partial fills), and addresses the dominant loss mode. Complete for a risk-check tool.

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

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

Schema description coverage is 100%, and the description adds extra context: explains default values for side and size_usd, clarifies auto-detection for basket mode side, and interprets size_usd differently for single-market vs basket modes.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific return fields and differentiates from sibling tools like polymarket_arbitrage and 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?

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why: theoretical overround on thin books is not capturable and partial basket fills convert arb into unhedged directional positions.

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, destructiveHint), the description adds detailed behavioral traits: safety fields like compatibility_warning with two cases, temporal_alignment, and skipped_cross_type/subtype counters. It warns that real spreads are rarer than the shortcut list suggests, which is crucial for agent decision-making.

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 thorough, but somewhat verbose. It front-loads the core purpose, then dives into detailed safety fields and counters. Bullet points or clearer sectioning could improve readability without losing content.

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

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

Given the complexity of cross-venue comparisons and no output schema, the description fully covers what the tool does, how to use it, what the response contains (spreads, compatibility_warning, temporal_alignment), and how to interpret edge cases. It is 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 descriptions for all three parameters. The description explains the two modes, lists all 10 pre-mapped topics, and describes how explicit parameters override the topic. This adds significant meaning beyond the schema.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, with two modes. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and includes specific examples.

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

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

The description explains when to use the short topic mode vs explicit tickers, notes that pre-mapped topics often return compatibility warnings, and implies when the tool may not produce meaningful spreads (e.g., when temporal alignment is false). It could explicitly name alternatives but provides sufficient usage context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by explaining scoping to the agent's identifier and the dual behavior (retrieve by key or list all). No contradiction.

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

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

Two concise sentences with the core action front-loaded. No wasted words; each sentence contributes purpose, context, and pairing guidance.

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

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

For a simple read tool with one optional parameter and no output schema, the description covers behavior, scoping, and relationships. Annotations handle safety. 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?

The single optional parameter 'key' is described in the schema. The description adds that omitting key lists all keys, which is meaningful context beyond the schema's type definition.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys, using a specific verb and resource. It distinguishes from sibling tools remember and forget by describing complementary actions.

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

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

Provides explicit context on when to use (to look up stored context without re-deriving) and scoping (by identifier). Mentions pairing with remember and forget, guiding appropriate usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral details: returns specific fields (source, citation_uri, payload), mark_read flag behavior, and polling suitability. No contradictions; adds value 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?

Single paragraph, well-structured with purpose first. Each sentence contributes value. Could be slightly more concise but remains clear and informative.

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

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

No output schema, but description explains return fields. Parameters all documented. For a read-only list tool with good annotations, it covers essential behavior (polling, alternative endpoint, usage). Missing explicit pagination details but limit parameter covers it.

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

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

Schema coverage is 100%, so baseline is 3. Description explains 'type' with example 'sec_8k', 'since' as ISO timestamp, and 'mark_read' behavior. However, 'unread_only' is not mentioned in description but is in schema. Adds some meaning but not exhaustive.

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 pulls fired events from the subscription feed, specifying the resource (alerts) and action (pull/return). Distinguishes itself from siblings like subscribe or list_subscriptions by focusing on the alert feed content. Uses specific verb 'Pull' and identifies return fields.

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

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

Description provides explicit usage context: 'Polls work fine' and mentions an alternative access method via a REST endpoint for scripts/dashboards. Lacks explicit when-not-to-use or comparison to other tools, but context is sufficient for most cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral details: parallel fan-out to multiple sources, fallback logic, soft-failure for USPTO, accepted date formats (ISO and relative), and return structure (changes grouped, total_changes count, citations). No contradictions.

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

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

The description is a single efficient paragraph with front-loaded natural language examples. Every sentence adds value without redundancy, covering purpose, sources, fallback, date handling, and return format.

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 adequately explains the return format (changes grouped by source, total_changes, citation URIs). It covers edge cases (rate limiting, API sunset) and provides complete context for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, but the description enriches each parameter: type limited to 'company', since includes examples and recommended '30d' or '1m', value accepts ticker or CIK. This adds practical guidance 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 uses natural language examples ('What's new with X', 'latest on Y') and clearly states it provides a change feed for a company in a time window via one parallel call. It names the three data sources (SEC, GDELT/GNews, USPTO) and distinguishes itself from sibling tool entity_profile.

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

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

The description explicitly tells when to use this tool (e.g., 'news on Tesla recently') and when not to ('Use entity_profile instead when you want the static profile...'). It also explains fallback behavior between GDELT and GNews, providing clear context for tool selection.

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

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

Annotations already declare the tool as non-read-only, non-destructive, and idempotent. The description adds valuable context beyond annotations: scope ('scoped by your identifier'), persistence duration ('24 hours for anonymous sessions'), and that it stores key-value pairs. 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 brief (5 sentences) with the main action front-loaded. Every sentence contributes essential information: purpose, usage guidance, technical storage details, and companion tool references. No redundant or vague language.

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 2-parameter tool with no output schema and comprehensive annotations, the description covers purpose, usage, persistence, and collaboration with sibling tools. It fully equips an agent to decide when and how to invoke the tool.

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

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

Schema has 100% description coverage for both 'key' and 'value' parameters. The description adds meaning by providing concrete examples of keys ('subject_property', 'target_ticker', 'user_preference') and values ('findings, addresses, preferences, notes'), enhancing usability beyond the schema alone.

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

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

The description clearly states that the tool saves data for reuse across conversations or sessions, specifying key-value pair storage scoped by identifier. It distinguishes from siblings 'recall' and 'forget' by naming them as companions, ensuring no confusion.

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

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

The description explicitly states when to use: 'when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions alternatives: 'Pair with recall to retrieve later, forget to delete.' It provides context on persistence (authenticated vs anonymous) to guide appropriate usage.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds unique behavioral context beyond that: it cascades through multiple internal endpoints (implying multiple lookups) and auto-disambiguates company inputs, and it specifies the citation URIs returned. This helps an agent anticipate the tool's execution profile and output style.

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

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

The description is longer than minimal but well-structured: it front-loads example queries, gives a purpose statement, then uses a 'SUPPORTED TYPES' breakdown. While there is some redundancy ('Use FIRST' echoes the purpose), each section serves a distinct informational role and stays readable without excessive 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?

For a two-parameter tool with no output schema and strong annotations, the description covers the essential context: purpose, usage timing, input forms, output specifics, and internal behavior. It lacks explicit error-handling or ambiguity-resolution details, but the provided information is sufficient for an agent to select and invoke the tool correctly in most expected scenarios.

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

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

The schema already includes descriptions for both parameters, so the baseline is 3. The description adds meaningful semantics by detailing what each type value yields (SEC EDGAR fields for company, RxNorm fields for drug) and how the value parameter is interpreted (ticker, CIK, or name). This enrichment goes beyond the schema's basic descriptions.

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

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

The description opens with concrete user-phrase examples and then clearly states the core function: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It also enumerates supported entity types and specific outputs (ticker, CIK, RxCUI, etc.), distinctly positioning it as an identifier-lookup tool compared to siblings like entity_profile or compare_entities.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID,' providing a clear when-to-use rule. It further clarifies accepted input formats per type, enabling an agent to decide between company and drug lookups. However, it does not name alternative tools or explicitly state when not to use it, so it lacks explicit exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds behavioral details: it probes each entity using ai_visibility_check, ranks results, and returns a list with score, confidence, signal density. It also explains that models can include Anthropic (requiring an API key) and that context disambiguates common names. 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 four sentences, each adding value: first sentence states purpose, second explains mechanism, third gives a concrete usage example, fourth lists output elements. It is front-loaded and concise with no unnecessary words.

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

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

Given the tool's complexity (comparing multiple entities with optional models and context) and the absence of an output schema, the description covers all parameters and describes the output format (ranked list with score, confidence, signal density). It does not cover potential errors or limits, but the tool's purpose is well-explained.

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%, but the description adds meaning beyond the schema: it explains that the first entity is treated as the 'subject' for narrative, that 'workers-ai' is the free default model, that '_apiKey' is only needed if 'anthropic' is in models, and that context disambiguates common names. This provides helpful context for 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?

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and scope (multiple entities). It also distinguishes from the sibling tool 'ai_visibility_check' by implying this is for multi-entity comparison, and mentions probing each entity with that 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?

The description gives a concrete use case: 'competitive AI-marketing audits' and an example question ('does Claude know about us as well as our competitors?'). It implies when to use this tool (multi-entity comparison) but does not explicitly state when not to use it or name alternatives, though the context suggests using ai_visibility_check for single entities.

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 safe read-only operation. Description adds critical behavioral context: fans out across multiple services, potential 5-30s delay for bundlephobia first measurement, graceful degradation with sources_failed field. 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?

Single dense paragraph, front-loaded with purpose. Every sentence adds value, but could be slightly restructured for readability. Efficient use of words given the complexity.

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

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

No output schema, so description must explain returns. It does so thoroughly: summary block fields, per-advisory details, links, alternative versions. Also covers error handling and ecosystem scope. Nothing missing for this 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%, so baseline is 3. Description adds value by noting that version defaults to latest and that scoped packages are accepted. While schema already describes parameters, the description provides additional usage context.

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

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

Description clearly states the tool's purpose: a composite check for npm packages using deps.dev and bundlephobia. It specifies the verb (scan/check), the resource (npm packages), and distinguishes from siblings by being a multi-source composite call.

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: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear 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?

Discloses technical details beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)'. Annotations already indicate idempotent and read-only, and description reinforces safe behavior. 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?

Concise, front-loaded paragraph of 5 sentences. Every sentence adds distinct value: purpose, use case, pairing suggestion, technical details, and limitations. No fluff.

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

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

For a tool with no output schema, the description clearly explains what is returned (top-N passages with character offsets and similarity scores). Covers essential behavioral aspects (embedding method, window size, character limit, truncation flag). Complements annotations and schema perfectly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by providing examples for the 'query' parameter (e.g., 'supply-chain risk') and clarifying that the 'text' parameter takes fetched document text. Also implicitly describes output (character offsets, similarity scores). Adds meaningful context beyond schema.

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

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

Explicitly states 'semantic search INSIDE a fetched record' with clear verb (search) and resource (inside fetched text). Distinguishes from siblings by specifying it works within a given text and pairs with 'ask_pipeworx_grounded' for grounding. No ambiguity.

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 usage scenario: 'Use when the record is too big to cram into the prompt—search_within saves context'. Also explains benefits (returning only relevant passages with offsets for verification) and suggests pairing with another tool ('ask_pipeworx_grounded'). 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?

Annotations indicate write behavior (readOnlyHint=false) and description confirms creation. Description adds value beyond annotations by disclosing OAuth requirements, SMS rate limits, and one-time webhook secret, but omits explicit mention of idempotency hinted 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 front-loaded with the core purpose, then details types and delivery. While lengthy, every sentence provides necessary information for correct invocation, earning its place without significant redundancy.

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

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

The description covers all necessary aspects: purpose, subscription types with parameters, delivery options with constraints, and prerequisites. Despite no output schema, it specifies 'Returns the new subscription id', making it 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%, providing baseline of 3. However, the description adds significant detail beyond the schema: specific examples for each type (e.g., items:['5.02'] for sec_8k) and constraints for delivery (phone verification, 10/day cap), which enhances parameter understanding.

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

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

The description states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly indicates the tool's action and result, distinguishing it from siblings 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?

The description explains usage context with delivery channels referencing recent_alerts as a way to pull from the feed, but does not explicitly contrast with siblings like list_subscriptions or unsubscribe. Still, it provides sufficient context for choosing when to use this tool.

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

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

Annotations already declare readOnly, idempotent, openWorld. Description adds return structure details (category-bucketed examples with tool shapes) and explains behavior (full spread vs topic focus). Adds useful context beyond annotations.

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

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

The description is thorough but could be trimmed; it front-loads the core purpose and lists categories efficiently. Given the complexity, it strikes a good balance.

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

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

No output schema exists, but description fully explains return format (category-bucketed examples with tool/argument shapes) and covers use cases (getting started, learning meta-tools). Complete for an onboarding tool.

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

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

Schema coverage is 100% with parameter description. Description adds value by clarifying default behavior ('Omit for a cross-category spread') and reiterating the enum focus areas.

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

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

The description clearly defines the tool as an onboarding entry point that returns category-bucketed example questions with tool and argument shapes, distinguishing it from query siblings like ask_pipeworx.

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

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

Explicitly states to use this first when unsure of what Pipeworx can do, and mentions passing topic to focus, with clear alternatives like meta-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?

Adds significant behavioral context beyond annotations: ownership enforced, deactivation vs deletion, and historical event availability via recent_alerts. Aligns with annotations (non-destructive, idempotent).

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, all information is relevant and front-loaded. No fluff.

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

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

Tool is simple (1 param, no output schema). Description fully covers purpose, side effects, ownership, and references sibling tool for historical data.

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

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

Schema coverage is 100%; the description mentions 'by id' but adds no extra meaning beyond the schema's parameter description. Baseline score applies.

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

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

The description clearly states the action (cancel), the resource (subscription), and the identifier (by id). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement (only your own subscriptions) and outcome (deactivation, not deletion). Does not mention when to avoid using or alternatives, 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 discloses that this tool replaces '4–6 sequential calls' and details the two internal pipelines (fast vs. grounded). Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds context about return values and evidence citation, which is useful beyond annotations.

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

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

The description is front-loaded with examples and a clear purpose statement. It is somewhat lengthy but every sentence adds information (purpose, routing, return value). It could be slightly more concise, but it is well-structured and efficient for the complexity.

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

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

Given the absence of an output schema, the description adequately explains the return format (verdict, actual value with citation, reasoning). With only 2 parameters (both fully described in schema) and clear behavioral notes, the description provides sufficient context for an AI agent to use the tool correctly.

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

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

The input schema already describes both parameters with 100% coverage. The description adds value by explaining the 'tolerance_pct' parameter overrides implied wording, suggests values for hallucination detection (1-2%), and notes the default and cap. This enriches the schema's meaning for an AI agent.

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

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

The description clearly states it performs natural-language claim verification against authoritative sources, with specific examples of query phrasing. It distinctly separates company-financial claims (SEC EDGAR + XBRL fast path) from other factual claims (grounded pipeline), differentiating its purpose from sibling tools.

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

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

The description explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It also explains the automatic routing for different claim types. However, it does not explicitly mention when not to use this tool or provide direct comparisons to sibling tools, though the context of claim verification is clear.

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