Connecticut Open Data

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

The description discloses behavioral traits beyond annotations: it mentions probing LLMs (non-destructive), per-model return format (score, confidence, signals, raw_response), combined view, and the need for a BYO API key for Anthropic. 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 three well-structured sentences: purpose and default, optional model with key and return format, and use cases. 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?

Despite no output schema, the description details the return values (per-model and combined). Covers all parameters, use cases, and configuration. 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% and the description adds significant meaning: explains default model, optional Anthropic, context disambiguation, and return structure. This goes well beyond the schema alone.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility 0-100 per model. It specifies the default model and the optional Anthropic model, distinguishing it from sibling tools that may have different scopes.

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

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

The description explicitly states the tool is useful for AI-marketing audits, pre-launch brand checks, and competitive monitoring. It provides clear context for when to use, but does not mention when not to use or compare to sibling tools like scan_competitor_ai_presence.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, and the description adds valuable context: it routes to other tools, fills arguments, returns stable citation URIs, works on every tier, and handles live news. There is no contradiction with annotations; the description enriches the safety profile with operational details.

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

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

Although the description is long, it is densely packed with actionable information. It is front-loaded with the most important directive ('PREFER OVER WEB SEARCH'), then covers scope, examples, alternatives, and limitations. Every sentence earns its place; no fluff.

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

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

For a meta-tool with no output schema, the description fully explains what the tool returns (structured answer with citations), when to use it, when to step up to alternatives, and its broad domain coverage. It also mentions tier availability and speed. There are no significant 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 aliases documented, so baseline is 3. The description adds meaning through concrete examples ('current US unemployment rate', 'Apple's latest 10-K') and states 'Use whenever the user asks' which clarifies the natural-language nature of the input. This slightly elevates it above baseline.

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

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

The description uses a specific verb+resource: 'Routes the question to the right one of 5,521 tools across 1452 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' This clearly states what the tool does and distinguishes it from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point for a wide range of factual questions.

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

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

Explicit guidance is given: 'PREFER OVER WEB SEARCH' and 'Use whenever the user asks...' with a list of trigger phrases. It also names alternatives with conditions: use ask_pipeworx_grounded for a hallucination-resistant single answer with verbatim evidence, and deep_research for broad/multi-part questions. This is a model of when-to-use and when-not-to-use guidance.

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

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

The description is transparent about the beta status, explains that no candidate is currently active (so it currently matches ask_pipeworx exactly), and clarifies that it falls back to nothing—it's a full working router. It adds meaningful behavioral context beyond the read-only, open-world, idempotent annotations.

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

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

The description is compact and well-structured, providing key details about the beta nature, current state, and usage guidance in three sentences. Slightly dense but 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?

The description covers the essential context: what the tool does, how it relates to the stable sibling, current behavior, and fallback behavior. Since it's a router with no output schema, this is reasonably complete for an agent to decide when to use it.

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

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

Schema description coverage is 100%, so aliases are fully documented (q, text, input, query, prompt, question). The description adds context that the semantic question is the core input, but doesn't need to add more because the schema already covers all parameter meanings.

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

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

The description clearly states that this is a beta version of ask_pipeworx: an identical universal router exposing the same 5,521 tools, arguments, and response shape, with optional candidate routing improvements. It distinguishes itself by emphasizing its experimental nature and live comparison against the stable ask_pipeworx router.

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

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

It explicitly says 'Use it exactly like ask_pipeworx' and provides context on when to choose this beta version (when wanting the newest routing). It doesn't explicitly list exclusions or alternatives beyond that, but the guidance is clear enough given sibling context.

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

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

Annotations declare the tool read-only, open-world, idempotent, and non-destructive. The description goes further by disclosing the refusal mechanism with specific refusal reasons, the return shape including verbatim evidence, the strict constraint of using only the tool result, and the extra LLM call cost. This is rich behavioral context beyond the annotations.

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

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

The description is only three sentences but packs a clear purpose, operational details, usage guidance, return format, and refusal reasons. It is front-loaded with the core purpose and every sentence adds value, with no wasteful repetition.

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

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

Despite the absence of an output schema, the description fully specifies both the success return object and the refusal return object with all fields and refusal reason enums. It explains routing across 5,521 tools, the extraction behavior, and the high-stakes use case. No significant gaps remain for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% description coverage for all parameters, with 'question' well-described and aliases explicitly listed. The tool description does not add parameter-specific semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states this is a hallucination-resistant answer mode for high-stakes reads, and explains the mechanism: routes to the right tool, fetches data, then extracts an answer using only the tool result. It distinguishes itself from the sibling ask_pipeworx by explicitly contrasting its grounded extraction and refusal behavior.

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 ('whenever an answer will be quoted, cited, or acted on') and when-not-to-use ('prefer ask_pipeworx for casual lookups'), including the cost trade-off of one extra LLM call. This directly addresses the alternative ask_pipeworx.

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

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

Annotations readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false are not contradicted. The description adds significant behavioral context: low-confidence short-circuiting, closed market handling, wide-spread liquidity, resolution-rule risk, and evidence source details. This goes well beyond the annotations.

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

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

The description is well-structured with clear headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the main purpose. However, it is verbose; some sentences could be condensed without losing information. For the complexity, it is appropriately sized but slightly long.

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 (classifiers, fan-out, response shapes, error handling, no output schema), the description is highly complete. It covers edge cases: low confidence, closed markets, wide spreads, resolution risk, raw data option. It essentially provides a mini-manual.

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

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

Schema description coverage is 100%. The description adds meaning beyond schema: explains market input formats, depth parameter (quick vs thorough), and include_raw usage (when to set true). Parameter behavior is richly described.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text), output (evidence packet + market-vs-model comparison), and usage examples. The tool is distinct from siblings like polymarket_arbitrage, polymarket_edges, etc.

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

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

The description provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes safety checks (resolver contract, cancellation rule). However, it lacks explicit when-not-to-use or 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: 'pulls LATEST 10-K revenue...', 'off-calendar fiscal years handled correctly', returns 'pipeworx:// citation URIs per entity', and 'results sorted by primary metric'. This goes beyond annotations, though rate limits or caching are not mentioned.

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

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

The description is a single dense block but packs essential information efficiently. Every sentence adds value—usage examples, data sources, ordering, and substitution benefit. It could be slightly more structured (e.g., bullet points), but overall it is concise and well-organized.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description covers key aspects: what it does, when to use, what data each type returns, and the substitution value. Missing details like error handling for invalid inputs or rate limits, but these are not critical. It places the tool in context of sibling tools by noting it replaces 8–15 sequential lookups.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: for type='company' it specifies data sources (SEC EDGAR/XBRL) and specific financial fields; for type='drug' it lists FAERS counts, FDA approvals, trial counts. It also clarifies the array items (tickers/CIKs for company, names for drug) and the maxItems=5 constraint.

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

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

The description clearly states it performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It uses specific verbs and resources ('compare', 'side-by-side comparison', 'companies or drugs') and distinguishes from sibling tools like entity_profile by emphasizing it replaces sequential lookups.

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

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

Explicit when-to-use guidance is given: phrases like 'compare X and Y', 'X vs Y', 'which is bigger', 'rank these companies', 'head to head'. It also states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear preference directive and context for avoiding alternatives.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it searches by keyword and returns specific fields, which aligns with read-only behavior. It provides extra context about return format and follow-up tool usage, adding 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?

The description is two sentences, front-loaded with the action and resource. Every sentence adds value: first states what it does, second explains the output and next step. No wasted words.

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

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

Despite no output schema, the description lists the returned fields (resource_id, name, description, category, update date) and how to proceed with the results. This is sufficient for an agent to understand the tool's output and integration point.

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

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

Schema coverage is 100% with each parameter described. The description adds no further meaning beyond the schema; it only mentions searching 'by keyword', which matches the query parameter. The baseline of 3 is appropriate since the schema already documents the parameters adequately.

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

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

The description clearly states the tool's action ('Search') and resource ('Connecticut Open Data catalog of open datasets'). It distinguishes itself from siblings by focusing on datasets specifically, with no confusion from similar sibling names.

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 returns and how to use the results (pass resource_id to query/metadata). It implicitly conveys when to use it (keyword search for datasets), but does not explicitly state when not to use it or mention alternatives, though none are apparent 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?

The description discloses extensive behavior beyond annotations: account/paid plan requirements, expected latency (15-60s, up to 90s), output structure (findings packet with verbatim evidence, confidence, source, fetched_at, citations), explicit gaps[] for unanswered facets, contradictions[] for standard/thorough, and semantic excerpting. This is far richer than the readOnly/idempotent annotations and shows the agent exactly what to expect.

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

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

The description is long, but every sentence adds critical context—account requirements, purpose, alternatives, depth semantics, output structure, and timeout expectations. It is front-loaded with the most important operational constraint (account) and uses clear section flow, so despite its length it is appropriately structured for a complex tool.

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

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

With no output schema, the description fully explains return values: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation', plus gaps[], contradictions[], and hop fields. It also covers failure modes (empty gaps for non-catalog topics) and performance expectations, making it exceptionally complete for a complex research tool.

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

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

The schema already covers 100% of the two parameters with detailed descriptions, so the baseline is 3. The description adds extra context: depth:'thorough' requires a paid plan, and depth:'standard'/'thorough' include a gap-recovery hop and contradictions scan, which reinforces the schema and clarifies real-world tradeoffs.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources' and explains it decomposes questions into facets routed in parallel. It explicitly distinguishes from siblings like ask_pipeworx, noting it's for broad/multi-part structured-data questions while single lookups go to ask_pipeworx, and it is not open-web search.

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

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

Gives explicit usage guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also states account requirements and when to choose depth levels, providing clear when-to-use vs 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=true, destructiveHint=false, idempotentHint=true. The description adds behavioral detail: returns top-N most relevant tools with full input schemas and curated examples, ready to call directly, and that it is a discovery tool, not a data retrieval tool.

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

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

The description is well-structured, front-loading the main purpose, then listing domains, explaining return format, and giving usage guidance. Every sentence adds value without redundancy.

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

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

Given the tool's purpose (discovery) and no output schema, the description fully explains what is returned (names, descriptions, full schemas) and how to use it. It is complete for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with all parameters described. The description adds value by explaining the aliases for 'query' and providing examples of natural language inputs, as well as clarifying the limit parameter's purpose (top-N).

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

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

The description explicitly states the tool is for discovering/finding tools by describing data or task, listing many domains. It distinguishes itself from sibling tools which are various specialized query tools, making the unique purpose clear.

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

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

The description gives explicit guidance to 'Call this FIRST when you have many tools available and want to see the option set.' It implies when not to use (when you already know the tool) but does not list explicit alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=True, openWorldHint=True, idempotentHint=True, and destructiveHint=False. The description adds substantial behavioral context: it 'fans out across multiple sources', 'soft-fails until reactivated' for patents, and lists exact return fields. No contradictions.

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

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

The description is verbose with multiple example queries and detailed data source enumeration. However, it is front-loaded with the core purpose and usage guidance. Some redundancy in examples could be trimmed for 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 no output schema, the description explains most return fields (cik, company_name, filings, fundamentals, patents, news, LEI) and limitations (patents sunset, name requirement). It could detail error handling or format specifics, but overall covers the tool's capabilities adequately.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds examples ('Pass ticker "AAPL" or zero-padded CIK "0000320193"') and clarifies name handling via resolve_entity, providing extra guidance beyond the schema.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific data points and explicitly distinguishes from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.'

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

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

The description provides explicit when-to-use guidance ('when the user asks for a holistic view'), and when-not-to-use ('names not supported – use resolve_entity first'). It also mentions the patents API sunset and soft-fail behavior, setting clear expectations.

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 hints. Description adds value by explaining appropriate usage contexts (stale data, sensitive data) but does not elaborate on edge cases like deleting non-existent keys.

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

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

Two sentences with no fluff. First sentence states primary action, second gives usage guidance. Highly efficient.

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

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

With a single parameter, full schema coverage, and clear annotations, the description covers all needed context. No output schema, but not required for delete operations.

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 description for the 'key' parameter. Description merely restates 'by key,' adding no new 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?

Description clearly specifies 'Delete a previously stored memory by key.' The verb and resource are distinct, and the mention of pairing with 'remember' and 'recall' helps differentiate 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?

Provides explicit contexts for when to use: context stale, task done, or clearing sensitive data. Also mentions pairing with related tools. Lacks explicit when-not, but is sufficient for a simple delete tool.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate safe, non-destructive behavior. The description adds valuable context: fetches page, extracts title/description/key links, emits standard markdown format, and notes output placement. 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?

Four sentences, front-loaded with the main action and purpose. No unnecessary words; every sentence earns its place by explaining function, use cases, and output format.

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

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

For a low-complexity tool (2 params, no output schema, simple text output), the description fully covers what it does, how it works, and what it produces. Annotations provide rich behavioral context, and the description complements them without gaps.

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

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

Schema description coverage is 100%; both parameters are documented. The description does not add new semantic meaning beyond what the schema provides (e.g., 'url' implicitly used in 'fetches the page', 'max_links' in 'maximum number of link entries'). Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Generate'), identifies the resource ('llms.txt file'), and specifies scope ('for any URL'). It distinguishes the tool from siblings, as none directly overlap.

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

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

The description explicitly lists three use cases (client site indexing, drafting own project, auditing competitor), providing clear when-to-use guidance. It lacks explicit 'when not to use' or alternatives, but the given scenarios are 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 declare read-only, idempotent, non-destructive. Description adds that it returns specific fields and defaults to active subscriptions, plus the include_inactive parameter. No contradictions.

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

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

Two sentences, front-loaded with core action, then usage guidance. 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?

Sufficient for a simple list tool with rich annotations; describes return fields and usage context. Could mention default value for include_inactive, but schema covers it.

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

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

Schema covers the single boolean parameter with 100% coverage. Description does not add extra meaning beyond what the schema's description already 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 the tool lists the caller's active subscriptions, specifies return fields, and is distinct from sibling tools like subscribe/unsubscribe.

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

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

Explicitly tells when to use: to review monitoring before adding more or to find an id to cancel. Implicitly excludes subscribe/unsubscribe actions.

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 safety traits (readOnly, idempotent, non-destructive). Description adds specific behavioral context: what metadata is returned (columns, types, row count, etc.), which is valuable beyond annotations. No contradictions.

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

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

Single sentence that front-loads the action and resource, with no extraneous information. Every word is 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?

For a simple one-parameter tool with no output schema, the description fully explains what the tool does and what it returns, making it complete for agent decision-making.

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 reinforces the parameter meaning and provides an example, adding clarity beyond the schema description.

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

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

Description uses specific verb 'Get' with clear resource 'Connecticut Open Data dataset's schema + metadata' and lists returned fields (columns, types, row count, category, last-updated). It distinguishes from siblings like 'datasets' and 'query' by focusing on schema/metadata retrieval.

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

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

Description provides clear context for use: when needing schema/metadata of a dataset by resource_id. It does not explicitly state when not to use or name alternatives, but the context is sufficient given sibling tool names.

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

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

Beyond the sparse annotations (all false), the description discloses the claim_token return behavior, daily digest review, roadmap influence, rate limit of 5 per identifier per day, and that it's free. These are valuable behavioral traits not visible from annotations or 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?

Description is long but every sentence adds purposeful information: what, when, exclusions, claim_token workflow, rate limits. It is well-structured with a logical flow, though slightly dense; still earns its length.

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

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

The tool has no output schema, but the description compensates by explaining the claim_token response pattern and how to read it later. It also covers prerequisite knowledge (which tools are Pipeworx's), making the description fully self-sufficient for a novice agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantics by explaining when to use claim_token (pass it back later with no other arguments to read status), and instructs not to paste end-user prompts in the message, which clarifies the intent beyond the schema's 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?

Description states exactly what the tool does: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb (tell/send) and resource (Pipeworx feedback), and distinguishes itself from sibling tools by explicitly excluding feedback about other MCP servers and naming the connection's 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?

Provides explicit when-to-use guidance for bugs, feature/data_gap, and praise, plus a clear when-not-to-use: reporting issues for tools from other MCP servers. It also explains the claim_token flow for follow-up, giving complete usage context.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable context: data source (CF analytics-engine), no PII, cached 5min-1h depending on window. This fully informs the agent about behavior beyond the annotations.

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

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

The description is a single focused paragraph (~80 words) with front-loaded purpose, followed by bullet-like use cases, then data source and caching info. Every sentence adds value, no fluff.

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

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

Given no output schema, the description mentions 'top tools, top packs, total call volume' and 'just (pack, tool, count)'. This provides enough structure for an agent to interpret the response. Caching and window specifics are covered. Minor gap: exact format of output not specified, but sufficient for a simple tool.

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

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

Schema coverage is 100% with enum descriptions. The description adds meaning: shorter windows surface what's hot right now, longer windows show steady-state demand. This helps the agent choose appropriate window values.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' with specific time windows. The verb 'returns' and resource (trending data) are explicit. It distinguishes from siblings (e.g., query, ask_pipeworx) by focusing on aggregate agent usage rather than direct Q&A.

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

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

Three specific use cases are listed (discovering hot data sources, confirming canonical tool choice, aligning use case with agent needs). Window semantics are explained (short vs long windows). However, no explicit 'when not to use' or alternative tool comparison is provided.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds extensive behavioral details: internal algorithms (date-axis ordering, partition_check, Jaccard similarity filtering, placeholder filtering, fill check with CLOB depth), response structure, and trade recommendations. No contradiction with annotations.

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

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

Description is lengthy but information-dense and well-structured, with key points front-loaded (purpose, mode selection). Every sentence adds value, though slight verbosity could be trimmed. Still effective and clear.

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

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

Given the tool's complexity (three modes, multiple filtering steps, fill check), the description is remarkably complete. It explains all essential behaviors, response fields (opportunities[], partition_check, fill_check), and trade decisions. No output schema, so description fully compensates. Also guides usage of sibling tools when appropriate.

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 both 'event' and 'topic'. Description adds value beyond schema by explaining each parameter's purpose, mode selection, example values (e.g., 'fed-decision-may-2026'), and acceptance of full Polymarket URLs. Provides context on how parameters affect behavior.

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

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

Description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific behaviors, differentiating from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly explains when to use each mode: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic for a themed cross-event scan'. Includes recommendations, exclusions (e.g., 'do not trade it' when fill check fails), and references sibling tool polymarket_fill_risk for custom sizing.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are fully supported and enriched by the description. The description details caching behavior (1h at KV level), model assumptions (FRED log-returns, GDELT volumes), and diagnostic elements (funnel counters, filter_skips), providing substantial behavioral context beyond the annotations.

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

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

The description is very long and detailed. While well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.), it contains extensive technical detail that may be overwhelming. The front-loaded purpose sentence is good, but the description as a whole could be more concise without losing essential information.

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

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

Given the tool's complexity (9 parameters, no output schema, rich analytical output), the description is remarkably complete. It explains the three model families, response structure (by_segment), tradeable-edge knobs (min_liquidity, max_spread_pp, etc.), diagnostics, caching, and even why Fed bets are excluded. No information gaps for effective 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?

Schema description coverage is 100%, so parameters are well-documented. The description adds value by explaining rationale (e.g., 'Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade' for slippage_pp) and how knobs interact (e.g., min_partition_leg_kelly vs min_kelly). It could be slightly more concise in parameter 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It identifies a specific use case ('what should I bet on today') and distinguishes itself from siblings by focusing on model-data disagreement and the Pipeworx edge.

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 implicitly guides usage by explaining the tool's design for discovering opportunities without paging. It details the model families, response structure, and knobs for filtering. However, it does not explicitly state when not to use this tool compared to siblings like polymarket_arbitrage or polymarket_edge_tracker, though the context is clear.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds significant behavioral detail: history depth bounded by 60-day snapshot TTL, snapshots written on cache-miss (gaps mean no scan), decay from daily closes not intraday, and the full response structure (tracked, expired, snapshot_dates). This gives the agent thorough insight into the tool's behavior and limitations.

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 and front-loaded with the key question it answers. It efficiently packs a lot of information without being overly verbose. Minor redundancy with schema prevents a perfect score.

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

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

Despite lacking an output schema, the description fully documents the response structure, parameter semantics, limitations, and data source. For a tool of this complexity, the description is complete and leaves no major gaps for the agent.

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

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

Schema coverage is 100% and the parameters are fully described in the schema. The description repeats the parameter defaults and possible values (days, window) but adds no new semantic meaning beyond the schema. According to rubric, baseline is 3 when schema coverage is high.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?', distinguishing it from the sibling tool 'polymarket_edges' which likely handles the raw snapshot data.

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

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

The description gives clear context for when to use this tool (for historical edge analysis) and explains that a fresh wide edge vs an old one represent different trades. However, it does not explicitly state when not to use it or name alternative tools, though the sibling list provides context.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, consistent with the described check. The description adds behavioral details such as walking the order book ladder, returning verdicts (clean|degraded|cannot_fill), and warning about partial basket fills causing unhedged directional risk.

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

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

The description is relatively long due to the tool's complexity, but it is well-structured with labeled sections (SINGLE-MARKET, BASKET) and front-loaded with the core purpose. Every sentence adds necessary context, 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?

Despite lacking an output schema, the description thoroughly enumerates all return fields for both modes, including edge cases like thin_legs, forced_directional_risk, and max_clean_notional_usd. It also provides practical usage warnings and integrates with sibling tool workflows.

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

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

Input schema provides 100% coverage with descriptions for all parameters. The description adds significant semantic value by explaining side defaults and mode-specific behavior, size_usd interpretation (max spend vs. target proceeds, settlement notional for basket), and mutual exclusivity of market and event.

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 between single-market and basket modes and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) for differentiation.

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

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

The description explicitly states 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 the requirement for one of market or event parameters and provides clear mode-specific 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 cover readOnly, idempotent, openWorld, and non-destructive behavior. The description adds significant detail about compatibility checks, temporal alignment, and skipped comparisons, which goes beyond annotations without contradicting them.

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

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

The description is dense but well-structured, front-loading the overall purpose then detailing modes, response, and safety fields. While lengthy, each sentence adds value; no redundancy.

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

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

Given the tool's complexity (three optional parameters, no output schema), the description thoroughly explains response structure, safety warnings, and limitations (e.g., temporal alignment, compatibility warnings). Leaves little ambiguity.

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

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

Input schema covers all parameters with descriptions, so baseline is 3. The description adds context by enumerating valid topic values and explaining how explicit tickers override topics, enhancing usability.

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

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

The description clearly identifies the tool as computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It differentiates from sibling tools like polymarket_arbitrage by specifying the cross-venue 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?

Provides explicit guidance on when to use each mode: topic shortcuts for pre-mapped macros, explicit tickers for custom pairs. Details safety fields (compatibility_warning, temporal_alignment) that signal when spreads are not meaningful, thus guiding appropriate usage.

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

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

Annotations already declare readOnlyHint and non-destructive behavior. The description adds that it returns JSON, but does not contradict annotations. Additional behavioral context beyond annotations is minimal.

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

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

The description is two sentences, front-loading the core purpose. Every sentence is informative and there is no redundant wording.

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 states the return format (JSON rows). Examples in the input schema provide further clarity. Completeness is high for a query tool.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds no new parameter semantics beyond mentioning SoQL clauses and examples.

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

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

The description clearly states the tool runs a SoQL query against a Connecticut Open Data dataset using a resource_id, and lists filtering clauses. This is specific and distinguishes it from sibling tools like 'datasets' or 'metadata'.

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 on using SoQL clauses without the leading $, and includes examples. However, it does not explicitly state when not to use this tool or mention alternatives among sibling tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping detail (by identifier) and pairing with remember/forget, providing useful context beyond annotations.

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

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

Two sentences, front-loaded with main action, no fluff. Every sentence adds value.

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

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

Given no output schema, description explains return behavior (value vs list). Also covers scoping and pairing with other tools. Sufficient for a simple retrieval tool.

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

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

Only one optional parameter 'key' with clear explanation in description: 'Memory key to retrieve (omit to list all keys)'. Schema coverage is 100%, description adds clarity.

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

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

Description clearly states the tool retrieves a value by key or lists all keys. Uses specific verbs (retrieve, list) and resource (saved memory). Distinguishes from siblings remember and forget.

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

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

Explicitly describes when to use: to look up previously stored context without re-deriving. Mentions scoping but does not explicitly state when not to use or list alternatives beyond remember/forget.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds valuable context: it reveals the mark_read flag modifies state (flagging events as read), the returned fields, and that polls work fine. No contradictions with annotations.

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

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

Four sentences, front-loaded with main action, each sentence adds distinct value. No unnecessary words; includes purpose, fields, filtering, state management, and alternative access in a compact form.

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 adequately explains return values (source, citation_uri, raw payload). Covers filtering, mark_read, unread_only, polling suitability, and alternative URL for scripts. With rich annotations, this is fully complete for a read-only 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 provides 100% coverage of 5 parameters with descriptions. The description adds semantics beyond schema: gives example for type filter ('sec_8k'), explains ISO timestamp for since, and clarifies mark_read behavior (next call shows newer only). Slight improvement could mention default limit behavior.

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 (Pull) and resource (fired events from subscription feed), specifies returned fields (source, citation_uri, raw payload), and distinguishes it from siblings by focusing on recent alerts from a persisted feed.

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

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

Provides clear context on when to use: for polling, filtering by type and since, and managing read state. Mentions alternative access (GET registry.pipeworx.io/alerts.json) but does not explicitly exclude when not to use or compare to sibling tools like list_subscriptions or query.

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 discloses fan-out to multiple sources, fallback logic (GDELT→GNews), soft-fail for USPTO, and return structure (grouped by source with citation URIs). No contradiction with annotations.

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

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

The description is comprehensive but slightly lengthy; however, every sentence adds necessary detail and it is well front-loaded with examples. Minor redundancy in the parameter descriptions.

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

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

Given the tool's complexity (multiple sources, fallback, parameter options) and absence of output schema, the description thoroughly explains behavior, return structure, and includes an alternative tool. 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%, but the description adds significant value: explains 'since' accepts ISO or relative shorthand with examples, clarifies 'type' is limited to 'company', and notes 'value' can be ticker or CIK.

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

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

The description clearly states the tool provides a change feed for a company over a time window, with example queries. It explicitly distinguishes from the sibling tool 'entity_profile' which serves static profiles.

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

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

The description provides explicit guidance on when to use this tool (change feed) vs. 'entity_profile' (static profile), recommends typical 'since' values like '30d' or '1m', and explains fallback behavior for news sources.

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 idempotent and non-destructive; description adds scoping by identifier, persistence differences for authenticated vs. anonymous users (24 hours), and pairing with recall/forget. No contradiction with annotations.

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

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

Three tightly packed sentences with no fluff: purpose, usage context, and behavioral details are all present and relevant.

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 simplicity (2 required string params, no output schema), the description covers all essential aspects: purpose, usage, scope, persistence, and related tools, leaving no gaps 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?

Both parameters have schema descriptions, but the description adds naming conventions (e.g., 'subject_property', 'target_ticker') and clarifies that value is free-text, which enhances understanding beyond schema.

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

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

Clear verb ('save') and resource ('data the agent will need to reuse later'), with specific examples (ticker, address, preference) that distinguish it from sibling tools recall and forget, which are explicitly mentioned.

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

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

States when to use ('when you discover something worth carrying forward') and why ('so you don't have to look it up again'). Mentions pairing with recall and forget, but lacks explicit 'when not to use' guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds meaningful behavioral context: it cascades through several lookup endpoints, returns citation URIs, auto-disambiguates company inputs, and specifies output fields per type. This goes well beyond the annotations and paints a rich behavioral picture.

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 usage examples and structured by supported types. It is somewhat long but every sentence adds value, including the cascade note and citation URIs. Slightly dense but not bloated.

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 compensates well by detailing exact return values for each type (ticker, CIK, company_name; RxCUI, ingredient, brand) and citation URIs. Combined with strong annotations and comprehensive parameter explanations, the tool is fully contextualized 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?

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description augments the schema with concrete examples (AAPL, 0000320193), accepted input variants (ticker/CIK/name for company; brand/generic for drug), and disambiguation behavior, earning a score above baseline.

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

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

The description clearly states a specific verb ('resolve') and resource ('user-spoken NAME to canonical/official identifier'), with multiple example phrasings. It distinguishes itself from sibling tools by focusing on name-to-ID resolution and explicitly says 'Use FIRST whenever you have a name but need an ID.'

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 provides an explicit trigger ('Use FIRST whenever you have a name but need an ID') and explains that it replaces 2-3 manual lookups. However, it does not explicitly name alternative tools to avoid or give when-not guidance, so it is strong but not fully explicit about exclusions.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. This is consistent and enriches understanding beyond the annotations.

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

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

The description is two sentences long, front-loaded with the core purpose, then details behavioral and usage specifics. Every sentence provides value; there is no redundancy or fluff.

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

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

Despite no output schema, the description clearly states what is returned: a ranked list with score, confidence, and signal density per entity. It covers all parameters and behavioral details (probing, ranking, comparison). The tool is of moderate complexity, and the description is complete.

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

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

All 4 parameters are described in the schema (100% coverage). The description adds meaning by explaining that the first entity is treated as the subject, that models defaults to 'workers-ai', that _apiKey is only needed for 'anthropic' model, and that context disambiguates. This assists the agent in parameter selection.

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

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

The description clearly states the tool's purpose: compare AI visibility across multiple entities, probe each with ai_visibility_check, and rank results. It gives a specific use case example ('does Claude know about us as well as our competitors?') and distinguishes from the sibling tool ai_visibility_check, which would handle single entities.

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

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

The description provides explicit context for use ('competitive AI-marketing audits') and a concrete example question. However, it does not explicitly state when not to use the tool or mention alternative tools like compare_entities for other comparison scenarios. The guidance is clear but lacks exclusion criteria.

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 adds transparency by detailing the composite fan-out, specific return fields, partial failure handling, and bundlephobia's initial measurement delay. 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?

Single dense paragraph that front-loads the main purpose, then efficiently adds details like return fields, limitations, and ecosystem scope. Every sentence contributes meaningful information without redundancy.

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

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

Despite no output schema, description enumerates return fields including summary block contents, per-advisory detail, links, and alternative versions. Covers external dependencies, timing caveat, and partial failure mechanism. Complete for the tool's complexity.

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

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

Input schema has 100% coverage with clear descriptions. Description adds value by confirming scoped packages are accepted and version defaults to latest, slightly extending schema 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?

Description clearly states the tool performs a composite npm package assessment across deps.dev and bundlephobia, with specific verb 'check'. It distinguishes from siblings by explicitly noting ecosystem scope and alternative tools for non-NPM packages.

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

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

Explicitly states when to use: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also provides context on partial failures, timeout expectations, and fallback to deps.dev:version for other ecosystems.

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 safety (readOnlyHint, idempotentHint, destructiveHint false). The description adds essential behavioral details: embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char overlapping windows), character limit (200K chars with truncation flag), and that passages include offsets for verification.

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

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

The description is concise, starting with the main purpose, then adding necessary details in a few sentences. No wasted words.

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

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

Given three parameters and no output schema, the description explains return values (top-N passages with offsets and similarity scores), covers the character limit, and provides usage context. It is sufficient for correct tool 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 description coverage is 100%, so parameters are already documented. The description adds practical context: text max length, limit range and default, query examples. This enriches understanding beyond the schema.

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

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

The description clearly states the tool performs 'Semantic search INSIDE a fetched record,' specifying the verb (search) and resource (a fetched record). It distinguishes itself from siblings by naming ask_pipeworx_grounded as a complementary tool.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded. Provides clear context and alternatives.

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

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

Discloses delivery channel behaviors, including SMS cap (10/day), phone verification requirement, webhook signing secret returned once, and auto-disable after 10 consecutive failures. This adds significant value beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description does not explicitly address idempotency, but the annotations hint at it.

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 with examples and technical details. It is front-loaded with the core purpose. Minor deduction for being somewhat lengthy, but every sentence provides essential information.

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

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

Covers the main purpose, required auth, supported types and their params, and delivery channel behaviors. However, it lacks a description of the full return format (beyond subscription ID) and does not mention error scenarios or expectations for idempotency. Given the complexity and absence of an output schema, the description is fairly complete.

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

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

Schema coverage is 100%, but the description adds rich examples and semantics for each subscription type and delivery channel, including constraints like phone verification and webhook HMAC signing. This goes well beyond the schema's brief descriptions.

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

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

Clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. The verb 'subscribe' is well-defined, and the description distinguishes it from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

Explicitly states the requirement for a Pipeworx OAuth account (anonymous+BYO cannot persist). It lists supported subscription types and their parameters. However, it doesn't directly contrast with alternative tools like recent_alerts or polymarket_edges, though it implies the feed is always on and can be pulled without subscribing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, making the tool's safe, non-destructive nature clear. The description adds valuable behavioral context: the tool returns 'category-bucketed example questions ... each with the exact tool + argument shape that answers it, drawn from the live catalog.' It also explains how the topic parameter changes behavior. No contradictions.

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

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

The description is well-structured: it starts with common user queries, then explains the purpose, output format, and usage. It is fairly long but efficient, using a list of example topics and clear call-to-action. Every sentence serves a purpose, though it could be slightly trimmed without losing meaning.

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

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

For a single-parameter tool with no output schema, the description provides complete context. It explains the output (category-bucketed example questions with tool+argument shapes), usage patterns (no args vs topic), and when to use it. No additional information is needed for an agent 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?

The input schema has 100% coverage with a single 'topic' parameter. The description adds meaning beyond the schema by listing example topics (finance, pharma, betting) and explaining that omitting it returns a cross-category spread. This helps the agent understand parameter usage without memorizing enums.

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

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

The description clearly states the tool's purpose as an onboarding entry point for discovering what Pipeworx can do. It provides specific example questions and explains the output format (category-bucketed example questions with tool+argument shapes). The sibling comparison suggests using this tool 'FIRST' when unfamiliar with Pipeworx, distinguishing it from other tools like ask_pipeworx or entity_profile.

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

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

The description explicitly states when to use the tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also provides clear usage guidance: call with no arguments for full spread, or pass a topic parameter to focus. No ambiguity.

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

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

Description adds value beyond annotations by explaining that the row is deactivated (not deleted) and that historical events remain accessible via 'recent_alerts'. Annotations already indicate non-destructiveness, but the description provides useful nuance.

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 that are front-loaded with the main action and constraint. Every word is necessary and contributes to understanding.

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

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

Given the single parameter, no output schema, and annotations covering safety, the description is fully sufficient. It covers the key behavioral aspects and constraints.

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

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

Only one parameter 'id' with schema description 'Subscription id (uuid) returned by subscribe.' Schema coverage is 100%, and description adds no additional semantic 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?

Description clearly states the action 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or provide alternatives.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, not destructive. The description goes beyond by explaining the two verification pipelines, the return structure (verdict, value with citation, reasoning), and that it replaces multiple calls. No contradiction with annotations.

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

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

The description is relatively long but well-structured: it starts with the core capability, then details pipelines, return values, and efficiency. Every sentence adds value, though it could be slightly more compact.

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

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

Despite no output schema, the description fully covers return values, parameter semantics, and two distinct verification pipelines. Given the tool's moderate complexity and complete schema coverage, it provides all necessary context for correct invocation.

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

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

Schema coverage is 100%, but the description adds meaning: for 'tolerance_pct', it explains overriding behavior, default, and usage for hallucination detection. It also gives concrete examples for the 'claim' parameter.

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

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

The description defines the tool's purpose clearly with specific verbs ('verify', 'fact check', 'confirm or refute') and identifies the resource (natural-language claims). It distinguishes the tool from siblings by noting it replaces 4-6 sequential calls and uses distinct pipelines for financial vs. other claims.

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

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

Explicitly states when to use ('whenever the agent needs to check whether something a user said is factually correct') and provides context on claim types (company-financial vs. other). No explicit when-not-to-use, but the guidance 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.