Data Vermont

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

Annotations already mark the tool as read-only and idempotent. The description adds behavioral details: per-model scoring with confidence and signals, raw response, combined view, and the API key passthrough mechanism. It does not cover rate limits or latency, but given the annotations, the added context is sufficient.

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

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

The description is three sentences, with the main purpose and outcome front-loaded, followed by essential parameter guidance and use cases. Every sentence provides distinct value; no redundancy.

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

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

Given the 4 parameters, no output schema, and comprehensive annotations, the description covers input details, return structure (per-model score/confidence/signals + combined view), and typical use cases. It omits potential restrictions like free model rate limits, but overall feels complete for an agent to use correctly.

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

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

Parameter schema coverage is 100%. The description enhances meaning with examples for 'entity' (e.g., 'Pipeworx', 'Acme Corp pricing'), explains the default model and API key usage for '_apiKey', and clarifies the optional 'context' parameter's purpose. It adds value 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 specifies the verb 'Probe', the resource 'business / brand / product / topic', and the outcome 'score visibility (0-100) per model'. It clearly distinguishes the tool's scope from siblings like 'scan_competitor_ai_presence' by focusing on multi-LLM probing with scoring, making the purpose unambiguous.

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

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

The description states it's 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring' and explains when to use the default model versus requiring an API key. However, it does not explicitly exclude other use cases or contrast with alternative tools, slightly reducing clarity.

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 carry the safety profile (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower and the description adds value beyond them: it discloses orchestration behavior (routing across thousands of tools), autonomous argument filling, and the citation-URI return format. It misses failure modes and rate limits, and some behavioral claims ('one fast call') are slightly muddied by the garbled tail, but there is no contradiction with annotations.

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

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

The opening is well front-loaded (PREFER OVER WEB SEARCH with domain list), but the tail degrades into apparent editing artifacts ('…', 'default entry point, one fast call. Step up only when needed:') and heavy redundancy — 'START HERE' appears twice, and the grounded/deep_research escalation guidance is stated twice in different words. Several sentences do not earn their place.

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

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

For an orchestration tool with no output schema and a single meaningful parameter, coverage is strong: purpose, scope, when-to-use, when-to-escalate, examples, and return format are all addressed. The garbled closing section and absence of response-shape or failure-mode detail are minor gaps that don't prevent correct selection and invocation.

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

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

Schema coverage is 100% (all six parameters are documented aliases of 'question'), so baseline is 3. The description adds genuine parameter-formulation guidance beyond the schema: natural-language question style, factual scope, and the advice to split multi-target questions or adjust ultra-short open-ended phrasing when the first answer misses. The schema examples overlap with description examples, but the formulation strategy tips push this above baseline.

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

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

The description names a specific verb (routes, fills, returns) and a precise resource (one of 5,798 tools across 1,517 verified sources) with a concrete output (structured answer with stable pipeworx:// citation URIs). It distinguishes itself from siblings by naming ask_pipeworx_grounded (citation-level verification) and deep_research (broad multi-source fan-out), so an agent can tell them apart without opening schemas.

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?

This is the strongest dimension: the description explicitly says to PREFER OVER WEB SEARCH, lists triggering utterance patterns ('what is', 'look up', 'find', 'get the latest', 'current'), gives six concrete example queries, and provides explicit step-up criteria ('strict citation-level verification → ask_pipeworx_grounded', 'REALLY big questions → deep_research'). It even gives simplification advice for ultra-short open-ended questions.

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 cover read-only, idempotent, non-destructive behavior. The description adds valuable context: the tool is a live experimental edge, candidate routing improvements are enabled only while under test, and currently no candidate is active so it matches ask_pipeworx exactly. It also clarifies it is a full working router, not a fallback stub.

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 beta identity and the key equivalence to ask_pipeworx. It is a bit wordy, but each sentence adds relevant information about current status, usage, and the experimental nature; there is no filler.

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

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

No output schema exists, but the description states the response shape matches ask_pipeworx and explains current behavior and how to use it. It doesn't describe the response contents in detail, but for a universal router with a stable sibling this is sufficient context.

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

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

Schema coverage is 100%, with each parameter described as an alias for question, so the schema carries the full parameter semantics. The description only says 'same arguments' without adding any meaning beyond the schema, so the baseline of 3 applies.

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

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

The description identifies the tool as a beta universal router identical to ask_pipeworx, with a specific scope: routing user questions across 5,798 tools. It explicitly differentiates itself as the experimental variant with candidate routing improvements, distinguishing it from the sibling 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?

It gives an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names the stable alternative ask_pipeworx and explains results are compared against it, but it does not explicitly state when-not-to-use or list other alternatives such as ask_pipeworx_grounded.

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

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

Despite readOnlyHint/openWorldHint/idempotentHint annotations, the description adds the critical behavior: it refuses rather than invents when data doesn't directly answer, enumerating refusal reasons. It also discloses the extra LLM call cost and grounded evidence format, which annotations cannot express.

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 dense sentences move from what it is to what it returns/refuses to when to use it, with no filler. Technical details like refusal_reason values are packed into the return contract rather than forced into prose.

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 high-stakes tool with no output schema, it fully describes the success and refusal payloads, the routing behavior, and the decision rule for choosing it over ask_pipeworx. The only omitted context (argument details) is addressed by 100% schema coverage and the link to ask_pipeworx's routing.

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 documents the single question parameter with all aliases at 100% coverage, so the description does not need to repeat parameter mechanics. It adds context about internal routing and argument-filling, but that is behavioral rather than user-facing parameter syntax.

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

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

States a specific verb ('answer') with a resource (Pipeworx) and the key behavioral distinction: extracts only from tool result rather than generating freely. Names the sibling ask_pipeworx and the 'same routing' relationship, which differentiates it without opening the schema.

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

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

Explicitly tells the agent when to use it: whenever an answer will be quoted, cited, or acted on, listing high-stakes domains. It also names the alternative (ask_pipeworx) and gives the trade-off condition: 'prefer ask_pipeworx for casual lookups.'

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description goes far beyond by detailing fan-out to data sources, response shapes (market, analysis, evidence), resolver contract, parent event extraction, news fields, safety mechanisms, wide-spread handling, and resolution rule risk. No contradictions with annotations.

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

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

Description is lengthy but well-structured with clear sections and examples. Front-loaded with purpose and input formats. Could be slightly more concise, but the detail is justified given tool complexity. Still earns a 4.

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 documents response shapes, edge cases, and field semantics. Covers resolver confidence, parent events, news error handling, and market closure scenarios. Complete enough for correct agent invocation.

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

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

Schema describes all three parameters with coverage 100%. Description adds significant value: explains market input formats (slug, URL, text), depth semantics ('quick' vs 'thorough' fan-out), and include_raw usage (summarized vs full payloads). Enriches understanding beyond schema.

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

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

Clearly states it researches a Polymarket bet using Pipeworx data. Specifies multiple input formats (slug, URL, question text) and output (evidence packet + market-vs-model comparison). Distinguishes itself from sibling tools like ask_pipeworx or deep_research by focusing on single bet analysis with a specific pipeline.

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

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

Provides explicit use cases (e.g., 'should I bet on X') and describes when responses short-circuit (low-confidence, closed markets). However, does not explicitly contrast with alternatives like validate_claim or polymarket_arbitrage, though the context implies uniqueness.

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

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

The description adds significant behavioral context beyond annotations: it details data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/ clinicaltrials.gov for drugs), explains handling of off-calendar fiscal years, states results sorted by primary metric, and mentions citation URIs. 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 fairly long but front-loaded with key trigger phrases and structured into sections (trigger words, functionality, type-specific details, behavior). Every sentence adds value, though minor redundancy could be trimmed.

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 return format (paired data + citation URIs) and sorting behavior, compensating for the lack of output schema. It could mention more about response structure or caching, but overall it is 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?

Input schema has 100% coverage with descriptions. The description adds examples ('AAPL','MSFT') and clarifies that values are tickers/CIKs for companies and names for drugs, enhancing semantic understanding beyond the schema.

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

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

The description explicitly states this tool performs side-by-side comparison of 2-5 companies or drugs. It lists trigger phrases like 'compare', 'X vs Y', 'head to head', clearly distinguishing it from single-entity tools like 'entity_profile'.

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

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

The description advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It does not explicitly state when not to use it (e.g., for more than 5 entities or non-comparison tasks), but the context 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds return format and follow-up guidance, enhancing transparency 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?

Two sentences, no waste. First sentence states purpose concisely, second explains output and usage. Front-loaded and efficient.

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

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

For a moderately complex tool (3 params, no nested objects, no output schema), the description fully covers purpose, output, and next steps. No gaps.

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

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

Schema coverage is 100% with descriptions for all three parameters (limit, query, offset). The description only mentions 'by keyword', aligning with query but adding no additional meaning beyond the schema.

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

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

The description clearly states 'Search the Vermont Open Data catalog of open datasets by keyword', specifying verb (search), resource (Vermont Open Data catalog), and action (by keyword). It also lists returned fields, distinguishing it from sibling tools.

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

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

The description explains what the tool does but does not explicitly state when to use it versus alternatives. However, it provides a clear follow-up action (pass resource_id to query/metadata), implying usage context. No exclusion criteria are given.

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

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

Annotations already mark this as readOnly, openWorld, and idempotent. The description goes well beyond them by explaining the internal decomposition/routing behavior, parallel tool invocation, findings packet structure, gaps[] for unanswered facets, contradictions[], citation URI behavior, semantic excerpting of large records, and expected latency. There is no contradiction with annotations.

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

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

The description is long, but nearly every sentence carries operational value: auth, alternative routing, scope, behavior, output packet, depth semantics, citation behavior, and latency. It is front-loaded with the most critical constraint (account required, use ask_pipeworx if not signed in). Its density is justified for a complex tool, though it could be better structured with line breaks.

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

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

With no output schema, the description carries the burden of explaining what the agent will receive. It covers the findings packet contents, evidence verbatim, confidence, source, fetched_at, citations, gaps[], contradictions[], excerpting, and timing estimates. It also explains how depth choices affect the execution path, leaving little ambiguity for an agent deciding to call this tool.

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

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

Schema coverage is 100%, so the baseline is already adequate. The description adds extra meaning by clarifying how depth values behave in practice: standard adds gap recovery and contradictions scanning, thorough adds iterative lead-chasing and requires payment, and question is suitable for broad/multi-part natural language queries.

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

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

The description states a specific verb and resource: grounded multi-source research across Pipeworx's 1517 structured data sources, explicitly clarifying it is NOT open-web search. It also distinguishes the tool from siblings by naming ask_pipeworx as the alternative for single lookups and for non-signed-in users.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, while single lookups should use ask_pipeworx instead. It also states the account requirement and that depth:'thorough' needs a paid plan, with a concrete fallback for unsigned-in users.

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 read-only and idempotent, and description adds that it returns top-N relevant tools with full schemas and examples, ready to call directly. No contradiction and complete behavioral context.

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

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

Description is concise, front-loaded with purpose, and every sentence adds value. No unnecessary verbosity.

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

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

Even without an output schema, description fully explains what is returned (names, descriptions, schemas, examples), which is sufficient for a discovery tool.

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

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

Schema coverage is 100%, but description adds value by explaining aliases (q, task, search, description) and providing natural language examples, making parameter usage clear beyond the schema.

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

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

The description clearly states the tool finds tools by describing data or task, lists specific domains, and distinguishes it from sibling tools which are mostly specific data tools, not discovery.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set' and 'use when you need to browse, search, look up, or discover', providing clear when-to-use guidance.

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

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

Annotations already establish readOnly, idempotent, and openWorld behavior; the description adds substantial beyond that: parallel fan-out across named sources, sources_used/sources_failed reporting, expected-empty sections such as FDA biologics for small-molecule companies, resolved:false handling for private companies, and type/value interchangeability. 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 dense with operational detail and front-loads the key guidance: holistic profile, prefer over chaining, then sources and edge cases. Some redundancy with the schema's parameter descriptions and a few run-on enumerations exist, but every section carries distinct useful 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?

This is a complex tool with many sources, multiple input forms, and no output schema. The description covers the full input contract, the return shape including cik, filings, fundamentals, patents, contracts, fda_products, hiring, news, LEI, and sources_used/failed, plus failure semantics for private companies. It omits only optional details like exact time windows or formatting, which are not required to invoke it correctly.

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

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

Schema coverage is 100%, and the schema already documents that type and value accept tickers, CIKs, or company names interchangeably. The description repeats this in prose and adds output-related nuances like resolved_from/resolved_to, but it does not materially add new parameter-level semantics beyond the schema.

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

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

The description clearly states the tool's purpose: producing a full cross-source profile of a US public company in one parallel call, with concrete user-intent examples. It differentiates the tool from chained single-source lookups and from siblings like resolve_entity and compare_entities by emphasizing holistic aggregation.

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 chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also defines valid inputs and the private-company edge case. It does not enumerate sibling tools by name or provide a strict 'don't use when' list, but the holistic-vs-single-lookup distinction is clear.

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

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

Annotations already indicate destructive and idempotent behaviors. Description adds context about clearing sensitive data but no new behavioral details beyond that.

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

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

Two sentences, front-loaded with purpose, zero waste. 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 single-parameter, no-output-schema tool, the description provides all necessary context: purpose, usage guidance, and sibling reference.

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

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

Schema covers 100% of parameter description. Tool description adds no additional meaning beyond the schema's 'Memory key to delete'.

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 (Delete) and the resource (a memory by key), distinguishing it from siblings like remember and recall.

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

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

Provides explicit usage contexts: stale context, task completion, clearing sensitive data. Mentions pairing with remember and recall, though no 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description explains the internal process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. It also specifies the output as a single text blob ready for deployment, providing full behavioral clarity.

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 (3 sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, process, and use cases. No redundant or extraneous information.

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

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

Given the tool's simplicity (2 params, no output schema, comprehensive annotations), the description covers all essential aspects: input, processing, output format, and usage scenarios. It is complete and leaves no significant gaps for an agent to infer.

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

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

With 100% schema description coverage for both parameters, the description adds minimal extra meaning—it implies that 'key links' are extracted, but does not elaborate on parameter syntax or constraints beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a given URL, specifying the action (generate), resource (llms.txt file), and context (for AI crawler indexing). It also lists three specific use cases, making the purpose highly explicit and actionable.

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

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

The description includes a 'Useful for' section that provides clear scenarios (client indexing, personal drafting, competitor auditing), effectively communicating when to use the tool. However, it does not explicitly mention when not to use it or alternatives among sibling tools like ai_visibility_check, which prevents a perfect score.

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

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

Annotations already indicate safe, idempotent, read-only behavior. Description adds context about returned data and optional parameter for inactive subscriptions, 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: first states action and return fields, second gives usage. No redundancies, perfectly front-loaded.

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

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

Given simplicity (list with bool param, no output schema), description covers purpose, return, usage, and parameter. Annotations cover safety. Complete.

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

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

Schema has 100% coverage with description for include_inactive. Description does not add extra parameter meaning beyond what schema provides.

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

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

Clearly states it lists the caller's active subscriptions and specifies return fields. Differentiates from siblings like subscribe/unsubscribe by focusing on reading.

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

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

Provides explicit guidance: use to review monitoring before adding more subscriptions or to find an ID to cancel. No alternatives mentioned, 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing a strong safety profile. The description adds value beyond these by detailing the specific metadata returned (columns, types, row count, etc.), which informs the agent about the output structure. There is no contradiction.

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

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

The description is a single, front-loaded sentence with an inline example. Every part is functional: verb, resource, specific elements, and example. 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?

Without an output schema, the description fully covers the return information: schema + metadata including columns, types, row count, category, and last-updated. It also specifies the resource_id format, making the tool's usage complete for an AI agent.

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

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

Schema coverage is 100%, with a clear description of the resource_id parameter. The description adds an example and context (e.g., Vermont Open Data), but since the schema already explains the parameter adequately, the description does not significantly augment semantics beyond 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 uses the verb 'Get' and specifies the resource as 'Vermont Open Data dataset's schema + metadata', listing concrete elements like columns, types, row count, category, and last-updated. It provides an example resource_id, making the purpose clear and distinct from sibling tools (e.g., datasets likely lists datasets, while metadata retrieves details for one).

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

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

The description implies usage when schema or metadata of a specific dataset is needed, but does not explicitly state when to use this tool over alternatives or when not to use it. No exclusion or sibling comparison is provided, though the context is clear enough for an AI agent.

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

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

Despite annotations all being false (no read-only/destructive hints), the description discloses key behaviors: anonymous filing returns a claim_token for later status checks, usage is rate-limited to 5 per identifier per day, and it doesn't count against tool-call quota. It also explains how to poll the token via pipeworx_feedback({claim_token:'pwfb_…'}), going beyond the schema.

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 a clear purpose and enumerates usage cases, but it runs to ~150 words and includes some redundancy with schema (e.g., claim_token description). All content is relevant and non-wasteful for the tool's complexity, though slightly more verbose 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?

The description covers the tool's scope, exclusions, claim_token lifecycle, rate limits, and quota impact, which is robust for a feedback tool. It doesn't specify the exact return shape when filing with an account (only the anonymous path), leaving a small gap given there's no output schema.

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

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

With 100% schema coverage, the baseline is 3, but the description adds critical semantics not in the schema: the claim_token's polling behavior and the requirement to describe issues in terms of Pipeworx tools/packs (not user prompts). This elevates parameter understanding well beyond the field descriptions.

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

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

The description opens with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the resource (Pipeworx team) and the types of feedback (bug, feature/data_gap, praise). It also explicitly distinguishes this tool from other Pipeworx tools by limiting it to feedback about tools served by this connection, not other MCP servers.

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

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

The description states exactly when to use the tool ('Use when a tool returns wrong/stale data...') and provides explicit exclusions: 'ONLY for tools served by this Pipeworx connection' and directs users to file complaints with other servers. It also gives a clarifying rule ('Pipeworx tool names are the ones this connection lists') and advises not to paste end-user prompts.

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

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

Annotations already provide readOnly, idempotent, non-destructive hints. Description adds derivation from CF analytics-engine, no PII, caching behavior. 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?

Two sentences plus bullet list. Front-loaded with core function. Every sentence adds distinct 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 simple input and no output schema, description adequately covers inputs, outputs, and caching. Could specify exact return format, but not necessary for clarity.

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?

Single parameter 'window' with enum values. Description adds semantic meaning: short windows for hot trends, long for steady-state. Schema already describes each value; description enhances.

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

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

Clearly states it returns top tools, packs, and volume over a time window. Uses specific verb and resource. Distinguishes from siblings like discover_tools by focusing on trending activity.

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

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

Explicitly lists three concrete use cases (discovery, confirmation, alignment). Does not exclude alternatives but the context is clear. Could mention when not to use, but sufficient.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds rich behavioral context such as semantic anchor filtering (Jaccard similarity ≥0.30), partition placeholder filtering, and fill check logic. However, the description is somewhat lengthy, which slightly reduces clarity.

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 clear sections for each mode and check. It front-loads the core purpose and then elaborates. Some sentences could be tighter, but overall it earns its length given the tool's complexity.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure: opportunities array with fields, partition_check details (including gap_from_1, placeholders_filtered), and fill check results. It covers edge cases like skipped_low_similarity and placeholder fraction limits.

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

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

Both parameters ('event' and 'topic') are fully covered in the input schema (100% coverage). The description adds significant value by detailing how each parameter is used, including examples of event slugs and seed questions, and explaining the behavior in each mode.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by specifying its unique analysis method and output signals.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, 'event' for specific market partition checks, and 'topic' for cross-event scanning. It also warns against trading when realizable_edge_pp ≤ 0 and recommends polymarket_fill_risk for custom sizing.

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

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

Beyond annotations (readOnlyHint, etc.), the description details the three model families, edge computation, tradeable-edge knobs, diagnostics, and caching behavior. No contradictions with annotations.

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

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

The description is excessively verbose, introducing detailed model mechanics and knobs that could be shortened or moved to schema documentation. While comprehensive, it sacrifices conciseness.

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

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

Given the tool's complexity (9 params, no output schema), the description covers response structure, diagnostics, caching, and edge computation thoroughly. No gaps identified.

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 by explaining each parameter's practical use, e.g., slippage_pp mentions Polymarket fees and advice. Adds context beyond schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, targeted at daily betting decisions. It specifies actions and resources, distinguishing from sibling tools like polymarket_arbitrage.

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

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

The description explains the tool is for discovering betting opportunities and notes caching behavior, but does not explicitly state when not to use it or compare to siblings. However, the context signals and sibling list imply differentiation.

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, and idempotentHint. The description adds significant extra context: history bounded by 60-day TTL, snapshots written on cache-miss, gaps mean no scan, and detailed return structure including computed trend and decay. This fully informs the agent of all behavioral traits 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 fairly long but every sentence adds value. It is front-loaded with the core question and explains return fields in detail. Minor redundancy could be trimmed, but overall it is efficient for the information conveyed.

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

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

Despite lacking an output schema, the description fully documents the return structure (tracked[], expired[], snapshot_dates[]) and addresses edge cases (gaps, TTL limits). For a tool with two parameters and moderate complexity, this is complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds marginal extra meaning (e.g., 'snapshot family' for window, 'lookback' for days) but does not provide syntax or format details beyond what the schema already states.

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, answering the specific question of how long an edge has existed and whether it is shrinking. This distinguishes it from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description implies when to use the tool by contrasting a fresh wide edge with a 3-week-old wide edge, indicating the tool helps assess edge persistence before trading. It does not explicitly state when not to use it or list alternatives, but the context is clear enough.

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

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

Annotations already mark the tool as readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds operational behavioral details: it walks the order-book ladder, returns specific metrics (vwap_fill_price, slippage_pp, verdict), and warns about partial basket fills stranding the agent unhedged. No contradiction exists between description and annotations.

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

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

The description is lengthy but well-structured with clear section headers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). The critical information is front-loaded. While some sentences could be tightened, every part earns its place by providing necessary operational detail.

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

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

Despite lacking an output schema, the description enumerates many return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). A few fields like 'market' in single-mode output are implied. This covers most of what an agent needs to interpret the result.

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

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

Schema description coverage is 100%, but the description adds significant value by explaining the dual interpretation of parameters: for single-market vs basket mode, and the default behavior for 'side' (auto from partition sum). It also clarifies that size_usd in basket mode represents 'settlement notional S (shares per leg)' rather than total spend. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by being a pre-trade risk check, and it specifies two distinct modes (single-market and basket) with explicit conditionals.

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

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

The description provides explicit guidance on when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why incomplete fills on baskets convert an arb into a directional position, effectively telling the agent when not to rely on theoretical edge alone.

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

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

Annotations already mark this read-only and idempotent, and the description adds substantial behavioral context: compatibility_codes semantics, temporal alignment null-meaning, gross-vs-net fee disclosure, unclassified legs never paired, and skipped comparison counters. The caveat that compatibility fields can be non-empty even when matched_pairs>0 is especially useful and not derivable from 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 and dense, but front-loaded with purpose and organized into modes, response shape, safety fields, and caveats. Some redundancy exists around 'either mode' and repeated compatibility codes, but the complexity of the tool justifies the length.

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

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

With no output schema, the description carries full responsibility for explaining the response, and it does so thoroughly: leg prices, top_spreads_pp, compatibility_codes[], per-entry flags, temporal_alignment, fees_note, skipped counters, and low-confidence pairs. It also handles edge interpretations like null alignment and non-empty warnings on matched pairs, leaving little to guess.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds value: it explains that both modes run identical token-overlap matching, that explicit parameters override topic-mapped sides, and that the same safety disclosures apply regardless of mode. This goes beyond the schema's simple field 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?

First sentence states the exact operation: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It also clarifies what makes the delta meaningful and identifies two specific modes, so an agent immediately knows what the tool does and how it differs from a generic pricing 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 explicitly separates topic mode (pre-mapped shortcuts) from explicit mode (custom kalshi_event_ticker + polymarket_event_slug), and clarifies that both run the same matcher. It also warns that pre-mapped topics are not automatically tradeable. It does not name sibling tools like polymarket_arbitrage as alternatives, so there is no 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 already declare readOnlyHint, idempotentHint, etc., so the description adds value by clarifying that SoQL clauses should omit the leading $ and that results are returned as JSON. No contradiction with annotations.

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

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

The description is two sentences, no filler. It packs purpose, resource, parameter usage, and output format efficiently.

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

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

For a query tool with 7 parameters fully documented in schema, the description covers key aspects: what the tool does, how to use parameters, and return format. Minor omission: no mention of default limit (covered in schema) or detailed pagination hints.

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 individual parameter descriptions. The tool description adds context about the SoQL syntax (no leading $) and provides examples that combine parameters, enhancing understanding beyond the schema.

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

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

The description clearly states the action (run a SoQL query) and the resource (Vermont Open Data dataset by resource_id). It distinguishes itself from sibling tools by specifying the target and query language, which no other sibling explicitly 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 explains how to use parameters (e.g., SoQL clauses without leading $, limit/offset) and provides examples. However, it does not explicitly advise when to use this tool versus alternatives like 'datasets' or 'search_within', leaving some 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 read-only, idempotent, non-destructive. Description adds context about scoping and listing behavior, complementing annotations without contradiction.

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

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

Three sentences, each adding value: main function, use case, scoping and related tools. No fluff, efficiently structured.

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

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

Complete for a simple retrieval tool: explains behavior with/without key, scoping, pairing with related tools, and aligns with annotations. No gaps.

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

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

Schema coverage is 100% and includes description for the key parameter. Description adds that omitting key lists all keys, but this is already in schema. Minimal added value beyond schema.

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

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

The description clearly states it retrieves saved values or lists keys, with specific verb 'Retrieve' and resource 'memory key' or 'saved keys'. It distinguishes from siblings like remember and forget by mentioning pairing.

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: look up stored context to avoid re-deriving. Mentions scoping but lacks explicit exclusions or alternatives beyond implied pairing.

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

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

Annotations already mark readOnlyHint=true, but the description reveals that setting mark_read:true flags events as read, implying a write operation. This is a contradiction, but the description does add context about mark_read behavior and alternative access.

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

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

The description is concise with 4 sentences, front-loaded with the main action. It could be more structured (e.g., bullet points), but it is efficient and not 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?

Given no output schema, the description explains what each alert carries (source, citation_uri, raw payload). It covers all optional parameters and behavior, including polling and an alternative REST endpoint.

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 a baseline of 3. The description adds concrete examples (e.g., type='sec_8k') and explains the effect of mark_read, going 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 pulls fired events from the subscription feed, specifying what each alert carries. However, it does not explicitly differentiate from sibling tools like list_subscriptions or subscribe, so it lacks sibling distinction.

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 mentions that polling works fine and provides an alternative REST endpoint, but does not explicitly guide when to use this tool versus others or state when not to use it.

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

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

The description adds significant behavioral context beyond the annotations: fans out to multiple data sources, fallback logic, soft-fail for patents, return structure. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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 informative, but it is a single paragraph without structuring aids like bullet points or section breaks. Still 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?

Despite no output schema, the description explains the return structure (changes[] grouped by source, total_changes count, citation URIs). It covers multiple data sources, fallbacks, and parameter details, making it 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?

The description adds meaning beyond the input schema: explains that type only supports 'company', gives examples for since (ISO vs relative), and clarifies value can be ticker or CIK. Schema coverage is 100%, so baseline is 3, but the extra context earns a 5.

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

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

The description clearly states the tool provides a change feed for a company (SEC, news, patents) and distinguishes from the sibling tool entity_profile by specifying when to use the latter instead. The verb 'recent changes' is specific and the examples clarify the use case.

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

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

The description gives explicit example queries and directs to entity_profile for static profiles. It also explains fallback behavior (GDELT→GNews) and the since parameter format. However, it does not explicitly state when not to use this tool or compare with other siblings beyond entity_profile.

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 idempotent, non-destructive write. Description adds valuable behavioral details: scope by identifier, persistence duration (24h vs persistent), which are not in 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?

Five sentences with clear front-loading of purpose. Every sentence adds value: purpose, usage, storage mechanism, persistence, related tools. No redundancy.

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

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

For a simple write tool with full schema coverage and annotations, the description covers purpose, usage, behavior, persistence, and sibling relationships. No missing information observed.

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

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

Input schema covers both parameters with descriptions (key examples, value text). Description doesn't add new semantics beyond schema, so baseline 3 is appropriate.

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

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

Description clearly states 'Save data the agent will need to reuse later' with specific verb (save) and resource (key-value memory). It distinguishes from siblings like 'recall' and 'forget' by naming them explicitly.

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

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

Provides explicit when-to-use guidance ('discover something worth carrying forward') with concrete examples (ticker, address, preference). Mentions pairing with recall and forget, offering clear 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 substantial non-obvious behavioral detail: the tool cascades through multiple endpoints internally, returns unresolved identifiers explicitly rather than omitting them, labels each identifier by source, and falls back to EDGAR identifiers when GLEIF/OpenFIGI are unavailable. None of this contradicts 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 long, but the length is justified by the tool's complexity and edge cases. It front-loads the core purpose and 'FIRST' guidance, uses clear typographic markers for supported types, and organizes caveats like ambiguity and degradation. A few phrases are redundant (e.g., repeated identifier-labeling details), but no sentence is wasted.

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

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

With no output schema, the description carries the burden of explaining what the tool returns, and it does: canonical identifiers per type, source labels, figi_candidates for ambiguous matches, unresolved fields, and the RxNorm citation URI. It also covers non-obvious inputs like ISIN and difficult cases like non-equity instruments, making it actionable without needing external 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%, but the description goes beyond it: it gives ticker/CIK/name examples for company, brand/generic examples for drug, and a crucial usage caveat — pass only the entity name, never the full noun phrase, because trailing security-class words will match nothing. This materially helps an agent construct correct input.

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 states a specific verb and resource: resolve a user-spoken NAME to canonical/official identifiers. It clearly distinguishes the tool from siblings by framing it as the first step before other tools that require IDs, and it explicitly enumerates supported entity types (company, drug).

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

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

It gives an explicit 'Use FIRST whenever you have a name but need an ID' directive, which tells an agent exactly when to invoke it. It also covers when results are ambiguous ('asserts nothing and returns figi_candidates') and notes graceful degradation when enrichment sources are unavailable, preventing misuse.

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

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

Annotations already mark readOnlyHint, idempotentHint, and destructiveHint false. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. No contradictions with annotations.

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

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

Two sentences front-loaded with purpose and method. Every sentence is informative. 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?

Without an output schema, the description adequately describes the return structure. It also explains the internal mechanism (calling ai_visibility_check). Combined with good annotations and full parameter descriptions, the tool is well-documented for an agent.

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

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

Schema has 100% coverage with descriptions for all 4 parameters. The description adds that the first entity is treated as the 'subject' for narrative and rest as competitors, adding slight nuance. Overall, schema already does heavy lifting, so description adds marginal value.

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

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

The description clearly states the verb 'compare' and resource 'AI visibility across multiple entities'. It specifies ranking, scoring, and surfaces which entity is most/least recognized. The purpose is distinct from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Provides explicit context: 'Useful for competitive AI-marketing audits' and an example question. Does not list when to avoid using this tool, but the context is clear enough to guide the agent. Implicitly excludes single-entity checks (use ai_visibility_check).

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds valuable behavioral details: bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully with sources_failed field, and the return structure (summary, advisories, links, versions). 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 appropriately sized for a complex tool. It is front-loaded with purpose, then usage, then behavioral details. Every sentence adds value, and there is no redundancy or extraneous information.

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

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

Despite lacking an output schema, the description adequately covers the return structure: summary block with specific fields, per-advisory detail, links, and alternative versions. For a tool with this complexity, the description provides sufficient context for correct invocation and expectation.

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 noting that scoped packages are accepted and that version defaults to latest when omitted. While schema already includes descriptions, the description reinforces and adds minor extras.

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

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

The description clearly states the tool's purpose: a composite check for adding npm packages, combining data from deps.dev and bundlephobia. It specifies the verb (check), resource (npm package), and scope (license, advisories, bundle size, etc.), distinguishing it from any 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 on when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also notes ecosystem limitations (NPM only in v1) and suggests alternatives for other ecosystems. Provides context on partial failures and timeouts.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral context: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, caps input at 200K chars with truncation and flagging. This goes well 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?

Description is about 6 sentences, front-loaded with purpose and usage. It is well-structured but slightly verbose in technical details. Every sentence adds value, so it 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 complexity (semantic search in large text), the description covers all necessary aspects: input constraints, algorithm details, return format, and pairing with another tool. No output schema exists, but the description compensates by explaining what is returned (passages, offsets, scores).

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: specifies max length for 'text' (200K chars), gives example queries for 'query', and states range and default for 'limit' (1-20, default 5). This exceeds basic schema descriptions.

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

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

Description clearly states it performs semantic search inside a fetched record. The verb 'search' and resource 'inside a fetched record' are specific. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and focusing on large documents.

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 to use when the record is too big to fit in the prompt, which is clear usage context. It also mentions pairing with ask_pipeworx_grounded. However, it does not explicitly state when not to use or name alternatives among siblings.

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

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

Annotations indicate the tool is not read-only, idempotent, and non-destructive. The description adds behavioral details: requires OAuth account, returns subscription id, delivery caps (10 SMS/day), webhook auto-disable after 10 failures, and HMAC signing. These go beyond annotations without contradiction.

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

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

The description is well-structured: purpose first, then requirements, types with examples, delivery details. Each sentence adds value, no redundancy. Despite length (~150 words), it remains focused 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?

The tool has no output schema, so the description correctly states the return value (subscription id). It covers requirements, types, parameter formats, delivery options, limits, and error handling (webhook auto-disable). Complete for a subscription creation tool with given 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%, but the description provides extensive additional meaning, such as interpretation of item codes (e.g., '5.02' = officer change), detailed delivery webhook setup (signing, secret, auto-disable), and type-specific parameter examples. This greatly aids correct parameter selection beyond the schema.

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

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

The description clearly states the verb 'Create a proactive monitoring subscription' and resource 'live-data event stream'. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation and providing specific subscription types.

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

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

The description specifies when to use (to create a subscription) and includes a prerequisite (OAuth account). It also mentions alternative channels for pulling alerts (recent_alerts), giving contextual guidance. However, it does not explicitly state when not to use or compare to all alternative sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. Description adds that calling with no arguments gives full spread and passing topic focuses it, plus details on return content.

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?

Front-loaded with common user queries, each sentence is informative. Slightly long but efficient for an onboarding tool.

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

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

Despite no output schema, description fully explains return format with category buckets and tool+argument shapes, and lists all available topics. No gaps 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%; description enriches by listing example topics (finance, pharma, etc.) and explaining that omission gives cross-category spread, adding context not in 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 is the 'onboarding entry point' that returns 'category-bucketed example questions' with tool+argument shapes, distinguishing it from siblings like ask_pipeworx and entity_profile.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do' and mentions how to call meta-tools. Lacks explicit when-not-to-use, 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?

Annotations indicate nondestructive (destructiveHint=false) and idempotent. The description adds value by explaining the row is deactivated (not deleted), which clarifies the behavioral nuance beyond structured fields. It also mentions ownership enforcement.

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

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

The description is very concise, consisting of two sentences that immediately state the purpose and then add key behavioral details. 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 simplicity (one parameter, no output schema), the description adequately covers the necessary context: what it does, ownership constraint, and deactivation behavior. It is complete for agent use.

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

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

The schema has 100% coverage with a clear description for the 'id' parameter. The description does not add additional meaning beyond what the schema already provides, meeting 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 'Cancel a subscription by id,' specifying the action and resource. It distinguishes from 'subscribe' and 'list_subscriptions' siblings by adding ownership enforcement and explaining deactivation vs deletion.

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

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

The description explains ownership enforcement ('you can only cancel your own subscriptions'), providing context on when to use. It also notes that deactivation keeps historical events via recent_alerts, but does not explicitly mention when not to use or alternatives, which would be clearer.

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

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

Annotations already provide readOnly/idempotent safety, but the description goes far beyond: it defines the exact verdict categories, explains the crucial distinction between could_not_verify and unsupported, notes that could_not_verify is not evidence, and mentions citations and reasoning. It also explains error handling with verification_error. This is rich behavioral disclosure with 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 dense but well-structured, starting with immediate trigger phrases and logically progressing to usage, routing, outputs, and caveats. It could be slightly condensed, but every sentence provides unique value; the opening is front-loaded 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?

Given the tool's complexity—two routing paths, multiple verdicts, and error semantics—the description fully documents inputs, expected behavior, and return values. The absence of an output schema is compensated by explicit verdict enumeration and citation/reasoning details. It also contextualizes the tool as replacing multiple sequential calls, making it self-sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful usage nuance for tolerance_pct, explaining that values 1-2 are for hallucination detection and that default is implied by wording capped at 5. It also gives an example of the claim parameter. This exceeds schema-only semantics.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific verb 'validate' and resource 'claim'. It includes trigger phrases and distinguishes itself from generic ask/search tools by focusing on fact-checking with verdicts. The routing between SEC EDGAR and grounded pipeline further clarifies 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?

It explicitly states when to use: whenever the agent needs to check factual correctness of a user statement, and gives examples of natural-language triggers. It also describes the internal routing for company-financial vs. other claims, but does not explicitly mention alternatives or when not to use, so it falls short of the 5-level 'explicit when/when-not/alternatives' requirement.

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