Dataverse Harvard

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

The description adds value beyond annotations by explaining the return structure (per-model {score, confidence, signals, raw_response} + combined view) and the cost implications for using Anthropic (BYO key, you pay). Annotations already indicate read-only and non-destructive behavior.

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

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

The description is three sentences long, front-loaded with the primary action and output format, then adding key details about default model, pricing, and return structure. 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?

With 4 parameters, 1 required, no output schema, the description adequately explains the input parameters and the output format (per-model objects plus combined view). It also covers the optional pricing aspect. The tool is fairly simple, so this is sufficient.

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

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

Schema coverage is 100%, and the description adds meaningful context for each parameter: 'entity' is described as the thing to ask about with examples; 'models' lists supported values; '_apiKey' explains its necessity and cost implication; 'context' helps disambiguation. This goes beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility. It specifies the verb 'probe' and the resource 'LLMs', with a clear scoring output. However, it doesn't differentiate from sibling tools like 'scan_competitor_ai_presence' or 'compare_entities'.

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

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

The description provides examples of when to use the tool (AI-marketing audits, pre-launch checks, competitive monitoring) and explains the default vs. paid model options. However, it does not explicitly state when not to use this tool or suggest alternatives from the sibling list.

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

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

The description adds significant behavioral context beyond annotations: it routes to 5,564 tools, returns structured answers with pipeworx:// citation URIs, and is 'one fast call' working on every tier. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, so no contradiction. The extra details on routing and citation mechanism are valuable but not critical for safety.

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

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

The description is front-loaded with the primary purpose and preference over web search, then provides use cases, examples, and alternative tools. It is somewhat lengthy but each section earns its place. Minor redundancy (e.g., mentions of routing to many sources appear twice), but overall efficiently structured for decision-making.

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

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

Given the tool's complexity (routing across 5,564 tools) and the simple input schema (only question), the description adequately explains what happens (structured answer with citations), when to use it, and when to step up to siblings. No output schema exists, but the description mentions return format indirectly. A brief note on potential multistep behavior or latency would enhance completeness, but it's sufficient.

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

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

Schema description coverage is 100%, with each of the 6 parameters described as aliases for 'question'. The description does not add new parameter-level semantics beyond what the schema already states. The schema itself includes examples and natural language description. Baseline of 3 is appropriate since the schema fully covers parameter meaning.

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

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

The description uses the verb 'ask' and the resource 'Pipeworx', clearly stating it routes questions to 5,564 tools across 1462 verified sources for authoritative structured data. It distinguishes itself from siblings like ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad multi-part questions), making the purpose unambiguous.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides detailed when-to-use guidance: factual questions about real-world entities, events, numbers, with examples like 'current US unemployment rate', 'Apple's latest 10-K'. Also specifies when NOT to use it and steps up to alternatives: ask_pipeworx_grounded for single answers with confidence, deep_research for broad queries. This is definitive and actionable.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by explaining the beta behavior: candidates are tested live, results are compared for merge decisions, and no candidate is currently active. It transparently states it is the 'experimental edge' which is useful context beyond annotations.

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

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

The description is concise at three sentences, each serving a clear purpose: defining the beta nature, stating current inactive state, and explaining usage context. It could be slightly more front-loaded by leading with the identical nature, but overall it is efficient and lacks 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 (5,564 tools), rich annotations, and complete input schema, the description adequately covers the beta purpose, current state, and usage guidance. No output schema exists, but the description does not need to explain return values as it explicitly states same response shape as ask_pipeworx.

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 input schema already documents all six parameters including aliases. The description adds no additional parameter details beyond noting the same arguments as ask_pipeworx. Baseline 3 is appropriate as the schema handles the burden.

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 an experimental version of ask_pipeworx with the same 5,564 tools, same arguments, and same response shape. It explicitly distinguishes itself from the stable ask_pipeworx sibling by highlighting its role as a testbed for candidate routing improvements.

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

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

The description explicitly tells the agent to use it exactly like ask_pipeworx when wanting 'the newest routing' and explains that results are compared against the stable router to decide merges. It also clarifies that no candidate is active now, so it currently matches ask_pipeworx exactly, and notes it falls back to nothing because it is a full working router.

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

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

The description adds significant behavioral context beyond the annotations: it explains the tool is 'hallucination-resistant', returns explicit refusal reasons, and cites the extra LLM call cost. This aligns with the readOnlyHint and idempotentHint annotations, with 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 fairly detailed but each sentence serves a purpose: purpose, mechanism, return format, usage guidance, and cost trade-off. It is front-loaded and well-structured, though slightly longer than minimal.

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 (6 aliased parameters, no output schema), the description fully covers the operation, return format on success and failure, usage context, and cost trade-off. The agent has all necessary information to select and invoke the tool correctly.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description does not add new parameter-level details beyond the schema, but the overall clarity of the single conceptual parameter is adequate. Baseline 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and explains the extraction process using only tool result. It distinguishes itself from the sibling 'ask_pipeworx' by specifying it is for grounded answers, not casual lookups.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. It also advises to 'prefer ask_pipeworx for casual lookups' and mentions the extra cost, providing clear when-to-use and when-not-to-use guidance along with an alternative 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?

Description goes far beyond annotations, detailing result shapes, resolver contract, parent event extraction, news fallback behavior, safety mechanisms (low-confidence short-circuit, closed market handling, wide spread warnings), and resolution rule risk. Annotations indicate readOnly, idempotent, non-destructive; description adds valuable behavioral context without contradiction.

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

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

Description is long but well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Front-loaded with main purpose. Every sentence contributes to understanding the complex tool. Could be slightly more concise, but the structure aids readability.

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

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

No output schema, but description thoroughly explains return values including market details, analysis, evidence keys, resolver confidence, parent event, news fields, and edge cases (low confidence, closed markets, wide spreads, resolution risk). Covers all expected scenarios for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the 'market' parameter accepts slug, URL, or question text; 'depth' explanation of quick vs thorough; and 'include_raw' default behavior and when to use. Meaningfully supplements 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 researches Polymarket bets by pulling Pipeworx data. It specifies the action (research), resource (Polymarket bet), and the process (resolve, classify, fan out, return evidence). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on research and evidence gathering.

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

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

Explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides examples of fan-out per classifier, giving clear context. Does not explicitly state when not to use or alternatives, but the context is sufficient for typical use.

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

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

Beyond annotations (readOnly, idempotent), description adds specifics: pulls latest financial data, handles off-calendar fiscal years, performs sorting by primary metric, and returns citation URIs. No contradictions.

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

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

Description is well-structured with examples, preference statement, and data details. Slightly long but highly informative; 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?

With only 2 parameters and no output schema, description fully covers usage, data source, behavior, and expected output, making it 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 is 100% covered; description enhances by specifying acceptable inputs for 'values' (tickers/CIKs for companies, drug names) and explaining what data is retrieved for each type, adding meaning beyond schema 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?

Description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides specific example queries and distinguishes from sequential single-pack lookups, making purpose unambiguous.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and details when each entity type is appropriate (company vs drug), providing clear guidance on when to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds no additional behavioral traits beyond confirming it retrieves metadata. It is consistent but does not enhance transparency 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 sentence that is concise and front-loaded with the key information. No unnecessary words, though it could be more explicit with an action verb.

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 is a simple metadata lookup with one parameter and an output schema exists, the description is sufficient. It covers the input format and purpose, though it could mention that the output contains the full metadata object.

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

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

Schema has 0% description coverage for the single parameter 'persistent_id'. The description adds meaning by specifying it expects a DOI persistent ID (e.g., doi:10.7910/DVN/...), which clarifies the format beyond the schema's type definition.

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

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

The description clearly states the tool retrieves dataset metadata using a DOI persistent ID, with an example format. It distinguishes from sibling 'dataset_files' which handles files. However, it does not explicitly state the action verb (e.g., 'Retrieve'), but the purpose is 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 provides no guidance on when to use this tool versus alternatives, such as 'dataset_files' or other search tools. It only describes what the tool does, not when it is appropriate to use or not use.

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

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

Annotations indicate readOnlyHint, idempotentHint, destructiveHint=false, and the description adds context that it returns file names, content types, sizes, and download URLs, and operates on the latest version. No contradictions; the description complements annotations well.

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

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

Two sentences, no wasted words, front-loaded with purpose and scope. Every sentence adds necessary 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 simple tool (one parameter, no nested objects), annotations cover safety, and an output schema exists (likely describing the returned fields), the description is complete. It covers usage, return values, and identifier format.

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 0% description coverage, so the description must add meaning. It provides an example and explains the format 'doi:10.7910/DVN/...', which is crucial for correct usage beyond the schema.

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

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

The description uses a specific verb ('list') and resource ('files in the latest version of a Harvard Dataverse dataset'), clearly distinguishes from siblings like 'dataset' by specifying it lists files with detailed properties, and includes the identifier format.

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 clearly states the tool is for listing files in the latest version given a DOI, but does not explicitly mention when not to use it or provide alternatives. The context is clear enough, but lacks 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 provide safety info (read-only, idempotent). The description adds the 'by alias or id' scope but no further behavioral traits. Adequate but minimal extra value.

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

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

Single sentence with no filler. Could be considered too minimal but still conveys core purpose efficiently.

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

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

Given the output schema exists and the tool is simple, the description is minimally complete. However, it does not explain what a dataverse is or how the identifier relates to the alias/ID distinction.

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

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

With 0% schema description coverage, the description says the parameter is an alias or ID, but no format or example details beyond the schema's example. Insufficient compensation for missing schema descriptions.

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

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

The description clearly states it retrieves metadata for a dataverse (collection) by alias or ID. It is specific enough to distinguish from sibling tools like 'dataset', though it could elaborate on what metadata includes.

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

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

No guidance on when to use this tool versus alternatives like 'dataset' or 'search'. Missing when-not scenarios and alternative tool suggestions.

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?

While annotations already indicate readOnlyHint=true and destructiveHint=false, the description adds extensive behavioral context: expectation of 15-60s latency (up to 90s for thorough), parallelism behavior, hop field and citation_uri details, semantic excerpting behavior, and gaps[] structure. It also clarifies that deep_research returns mostly empty gaps for unsupported topics, which annotations don't cover.

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 moderately long but front-loaded with critical prerequisites (account requirement, alternative tool). Every sentence provides meaningful guidance. Minor density could be improved by separating usage guidelines from behavioral details, but overall efficient.

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

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

Despite no output schema, the description fully explains the return format (findings packet with verbatim evidence, confidence, source, citation, gaps[], contradictions[], etc.). For a complex tool with 2 parameters and no nested objects, this is complete. Covers authentication, latency, data sources, and edge cases.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by explaining the implications of each depth level (e.g., 'standard adds gap-recovery hop', 'thorough is paid and adds iterative leads chase'). The parameter descriptions in schema are detailed, but the description provides richer behavioral 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 it performs 'grounded multi-source research across structured data sources' and contrasts with open-web search. It specifies the exact verb ('research') and resource ('Pipeworx's structured data sources') and distinguishes from siblings like ask_pipeworx and ask_pipeworx_grounded.

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

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

Provides explicit when-to-use guidance: 'best for broad/multi-part questions over structured data'. Directs to alternatives: 'for a single lookup use ask_pipeworx', 'for BREAKING or colloquial CURRENT-NEWS...prefer ask_pipeworx'. Also notes that the tool requires an account and suggests ask_pipeworx for non-signed-in users.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, covering safety and side effects. The description adds important behavioral context: 'each result is ready to call directly, no second schema lookup needed,' which enhances usability but does not contradict annotations.

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

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

The description is concise at two sentences, front-loading purpose and usage. It avoids redundancy with the schema. However, the list of domains could be slightly more structured (e.g., bullet points) for readability, but overall it is efficient.

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

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

Given the tool's complexity (6 parameters, no output schema), the description adequately covers what the tool does, what it returns, and when to use it. The absence of output schema is compensated by describing returned items. Minor omission: the default limit (20) and max limit (50) are only in the schema, not in the description, but that's acceptable.

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

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

Schema coverage is 100%, with descriptions for all parameters. The description adds value by providing domain examples ('analyze housing market trends', 'look up FDA drug approvals') and clarifying that 'query' accepts aliases. This enriches the schema without redundancy.

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: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and explains the output: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas.' This distinguishes it from sibling tools like 'search' or 'deep_research' by focusing on tool discovery rather than data retrieval.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on precedence and 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 indicate read-only, idempotent, non-destructive. Description adds details about parallel fan-out across multiple sources, a patent API sunset soft-fail, and specific output fields. Does not contradict annotations.

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

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

Description is dense but well-structured: front-loaded with examples, then purpose, then detailed output. Every sentence adds value, though could be slightly more concise.

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

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

Given no output schema, description lists all return fields (CIK, filings with URIs, fundamentals, patents with caveat, news, LEI) and ordering. Lacks explicit structure for fundamentals but sufficient for agent use.

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

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

Schema coverage is 100% with param descriptions. Description adds context (e.g., only 'company' supported, names not supported, use resolve_entity as alternative) and example values, going 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 as providing a full cross-source profile of a US public company in a single parallel call, with examples like 'Tell me about X' and explicit preference over chaining single-pack lookups. It distinguishes from siblings by emphasizing holistic view.

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

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

Explicitly says to prefer this over chaining single-source tools for holistic queries, and that names are not supported—use resolve_entity first. Provides clear 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?

Annotations already declare destructiveHint=true and idempotentHint=true. The description reinforces the destructive nature and adds the behavioral context of clearing sensitive data, which is valuable beyond annotations. It could mention behavior on missing key, but the idempotent hint implies no error.

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 wasted words. First sentence states purpose, second provides usage guidance and related tools. Front-loaded and concise.

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

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

For a simple one-parameter delete tool with good annotations, the description covers purpose, usage, and related tools. It does not explain return values (not needed with no output schema) or edge cases, but it is sufficiently complete for the tool's complexity.

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

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

Schema coverage is 100% with one parameter described as 'Memory key to delete'. The description adds minimal extra meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory by key'. It distinguishes from siblings by explicitly mentioning 'remember' and 'recall' as paired tools.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also provides pairing guidance with 'remember' and 'recall', which are present in 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?

The description explains the internal process: fetches page, extracts title/description/links, and emits standard markdown. It adds context beyond the annotations (which already mark it as read-only, idempotent). No contradictions. Lacks mention of potential limitations like rate limits or size, but overall transparent.

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 efficient and front-loaded with the main purpose. It covers all needed aspects in a single paragraph. Minor redundancy in the 'Useful for' list, but overall well-structured and not overly verbose.

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

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

Despite no output schema, the description fully describes the output format ('single text blob ready to drop at site-root/llms.txt'). Combined with clear use cases and process, the description is complete for this simple tool with 2 parameters.

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

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

Schema coverage is 100% with both parameters already well-described in the schema. The description adds no additional meaning or usage context beyond the schema definitions, so it meets the baseline without bonus.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL. The verb 'generate' and resource 'llms.txt file' are specific, and the purpose is distinct from any sibling tools listed.

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 provides three distinct use cases: getting a client's site indexed, drafting for own project, and auditing competitor. This gives clear guidance on when to use the tool, and no sibling tool has overlapping functionality.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe, read-only operation. The description adds the specific return fields and the option to include inactive, but the behavioral profile is well-covered by 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?

Two sentences, no wasted words. First sentence states purpose and output fields. Second sentence gives usage advice. Efficient and well-structured.

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

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

Given the simplicity of the tool (single optional boolean, no nested objects, no output schema), the description covers purpose, parameters, and output fields. It could mention ordering or pagination, but not necessary for a basic list. A score of 4 reflects adequate completeness.

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

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

Schema coverage is 100% for the sole parameter include_inactive. The description mentions 'include_cancelled' but adds no semantic detail beyond what the schema already provides: 'Include cancelled subscriptions in the response (default false).' Baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions', specifying the verb (list), resource (subscriptions), and scope (caller's active). It distinguishes from sibling tools like subscribe/unsubscribe by focusing on reading existing subscriptions.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use it. It doesn't explicitly state when not to use, but the context is clear.

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

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

Discloses several behavioral details beyond annotations: rate limit (5 per identifier per day), free/no quota impact, the claim_token workflow for anonymous filing and later retrieval, and that team reads digests daily with roadmap impact. This adds rich context that all-false annotations do not convey. No contradiction with annotations.

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

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

The description is a single paragraph but every sentence earns its place: purpose, when/where to use, limitations, token workflow, rate limit, and cost. Information is front-loaded and direct, with no filler or repetition of schema content.

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

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

Despite having no output schema, the description explains what the tool returns (claim_token) and how to follow up. It also covers edge cases (different MCP server), user guidance (don't paste prompts), operational context (daily read, roadmap influence), and usage constraints (rate limit, cost). This is complete for a feedback tool of this complexity.

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

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

All 4 parameters are already fully documented in the schema (100% coverage), so baseline is 3. The description adds value by illustrating claim_token reuse ('pipeworx_feedback({claim_token:"pwfb_…"})') and by instructing users to describe issues in Pipeworx tool/pack terms rather than pasting prompts. This meaningfully supplements the schema without redundancy.

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 immediately states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the resource (Pipeworx team/connection) and the acceptable feedback types (bug, feature/data_gap, praise). It also distinguishes itself from sibling tools by excluding non-Pipeworx MCP servers and telling users to file those elsewhere.

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

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

Provides explicit 'Use when' guidance for bug, feature/data_gap, and praise. Gives a clear exclusion: 'if the tool came from a different MCP server ... file it with that server instead.' Offers a fallback heuristic ('Not sure? Pipeworx tool names are the ones this connection lists') to help ambiguity resolution.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable behavioral context beyond annotations: caching behavior (5min-1h), derivation method ('CF analytics-engine'), data privacy (no PII), and data structure (pack, tool, count). 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?

Approximately 80 words, well-structured with numbered use cases. Every sentence adds value. No redundancy or unnecessary fluff. Appropriate for the tool's simplicity.

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

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

For a tool with one optional parameter and no output schema, the description covers return values, caching, data source, privacy, and usage contexts. Annotations cover safety. Complete and self-contained.

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

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

Schema coverage is 100% and the schema description for the 'window' parameter already explains the options and trade-offs. The description restates this briefly but adds minimal new information beyond the enum values. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states what the tool does: 'What other AI agents are calling on Pipeworx right now.' It lists specific outputs (top tools, top packs, total call volume) and provides three usage categories. This distinguishes it from sibling tools like discover_tools or ask_pipeworx.

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

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

Description explicitly provides three use cases (discovering hot data sources, confirming canonical tool, seeing alignment). It implies when to use but does not include explicit 'when not to use' or alternatives. Still clear and helpful for the agent.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with a read-only analysis tool. The description adds extensive behavioral details: scanning mechanics, partition checks, semantic anchors, placeholder filters, and fill check logic. This goes far beyond what annotations provide, giving full transparency.

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

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

The description is thorough but somewhat lengthy (~250 words). It is well-structured with clear sections for each mode and important details (fill check note). Slightly verbose but every sentence adds value; only minor trimming could improve conciseness.

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

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

For a complex tool with 2 optional parameters and no output schema, the description provides comprehensive guidance: modal behavior, expected response structure, edge cases (placeholder slugs, thin legs), and links to sibling tools. It is self-contained and fully equips an AI agent to invoke correctly.

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

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

Schema coverage is 100% with concise descriptions for event and topic. The tool's description significantly augments the schema by explaining the exact usage of each parameter, the scanning behaviors triggered, and providing examples (e.g., event slug 'fed-decision-may-2026'). This adds substantial value.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk via explicit usage guidance.

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

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

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also directs users to polymarket_fill_risk for custom sizing, clearly differentiating from alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds beyond these by detailing model families, caching (1h KV-level), response structure (by_segment, diagnostics, fed_candidates), and filter behavior. It fully discloses the read-only, idempotent nature without contradiction.

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

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

The description is detailed and front-loads the core purpose, but it is quite long, with multiple paragraphs of technical details. It could be restructured to be more concise, though all information is relevant. The length is justified by the tool's complexity.

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

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

Given the complexity (9 parameters, multiple segments, no output schema), the description is fairly complete. It explains the response structure (by_segment, fed_candidates, _diagnostics) and the edge details. However, it lacks an example output or explicit explanation of return format beyond text, which would enhance completeness.

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

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

Schema coverage is 100% (all 9 parameters described in the input schema). The description adds extra context for some parameters (e.g., slippage_pp explains Polymarket fees, min_partition_leg_kelly explains per-leg Kelly), but overall it does not significantly increase meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool scans Polymarket markets to return opportunities where Pipeworx data disagrees with market price. It specifies the purpose as 'what should I bet on today' and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker, which likely focus on other aspects.

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

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

The description explicitly says it's for discovering opportunities without paging hundreds of markets. It provides context for when to use it but does not explicitly exclude alternatives or mention when not to use it. Sibling tools like polymarket_arbitrage and polymarket_edge_tracker exist but are not compared.

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 significant behavioral context beyond annotations: explains return structure (tracked, expired, snapshot_dates), decay computation, TTL limits, and missing data gaps. No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint are all consistent).

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

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

Description is somewhat lengthy but each sentence provides unique value. Front-loaded with purpose. Minor redundancy could be trimmed, but overall well-structured.

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

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

For a read-only tool with two optional parameters and no output schema, the description fully explains return values (tracked, expired, snapshot_dates), limits (60-day TTL), and edge cases (gaps in data). No missing information 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 coverage is 100% and description adds extra meaning: default values, valid ranges (clamp 2-30, max 30), and explanation of window parameter ('24hr | 1wk | 1mo'). Complements schema thoroughly.

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

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

Description clearly states the tool's purpose: edge persistence and decay telemetry, answering how long an edge has existed and whether it is shrinking. It uses specific verbs and resources, and distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage.

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

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

Description implies when to use (e.g., comparing fresh vs old edges) but does not explicitly state when not to use or provide direct alternatives among siblings. Usage context is implied but not explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, indicating a safe read operation. The description adds significant behavioral context: it walks the ladder, returns detailed outputs (top_of_book, vwap_fill_price, slippage_pp, etc.), and for basket mode explains per-leg fill detail, thin_legs, and forced_directional_risk. It also warns about the risk of partial basket fills converting arb into unhedged positions.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). While it is relatively long, every sentence serves a purpose given the complexity of the tool. It could be slightly more concise but remains effective.

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

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

Given the tool's complexity (4 parameters, no output schema), the description covers inputs, outputs, and usage context. It explains what each mode returns and provides critical usage warnings. The absence of an output schema is compensated by the explicit listing of returned fields and their interpretation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the difference between single-market and basket modes for the market and event parameters, clarifying side defaults and interpretations, and specifying that size_usd is interpreted differently for buys vs sells and for basket vs single-market. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and differentiates from siblings like polymarket_arbitrage and polymarket_edges by specifying that this tool should be used before acting on their signals.

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

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

The description 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 explains the rationale, noting that theoretical overround on thin books is not capturable and partial basket fills convert an arb into directional risk.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description goes beyond by detailing compatibility_warning conditions, temporal alignment, skipped legs, and the implication when bet shapes are non-equivalent. No contradiction.

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

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

The description is well-structured with clear sections and bolded terms, but it is somewhat verbose (around 300 words). Some redundancy could be trimmed, but for a complex tool, the detail is justified.

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

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

No output schema is provided, but the description thoroughly explains the response structure: leg-by-leg prices, matched spreads, safety fields, and compatibility warnings. It covers all important aspects for correct usage.

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

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

Schema coverage is 100% with good descriptions. The description adds value by explaining the topic enum values, the overriding behavior of explicit parameters, and example ticker formats. It provides meaningful context 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 computes cross-venue spread between Kalshi and Polymarket, with specific verb+resource and two distinct modes. It differentiates from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explains two modes (topic shortcuts and explicit tickers) but does not explicitly contrast with alternatives. However, it provides practical guidance by warning that most pre-mapped topics may not be tradeable, helping manage 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context, such as the effect of omitting the key argument (listing all keys) and the scoping to the agent's identifier. No contradiction.

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

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

Three sentences, no wasted words. The core action is stated first, followed by use cases and pairing information. Highly efficient and easy to parse.

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

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

Given the single optional parameter, no output schema, and comprehensive annotations, the description covers all necessary context: purpose, usage, pairing, and scoping. It is complete for effective 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 coverage is 100% with a clear description for the single parameter. The description adds value by explaining the behavior when the key is omitted (list all keys) versus provided (retrieve specific value), enhancing the schema's explanation.

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

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

The description uses specific verbs ('Retrieve', 'list') and clearly states the resource ('value previously saved via remember', 'all saved keys'). It distinguishes this tool from siblings (remember, forget) by describing its complementary role.

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

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

The description explains when to use the tool: 'look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with remember and forget, but does not explicitly state when not to use it or provide alternatives beyond the 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 already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: it returns the most recent alerts, can mark events as read, and notes that polling works 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?

The description is a single coherent paragraph of five sentences. It front-loads the purpose then details functionality. The mention of an alternative HTTP endpoint is slightly extraneous but not wasteful. Could be trimmed slightly, but still effective.

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

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

No output schema exists, but the description lists return fields (source, citation_uri, raw payload). Parameters are fully covered. The tool is simple and the description covers key behavioral aspects like mark_read and filtering. Minor gap: no mention of pagination beyond limit.

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

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

Schema coverage is 100%, so the schema already describes each parameter. The description adds context for mark_read (flagging events as read) and mentions filtering by type/since, but this is mostly redundant with schema descriptions. The extra explanation adds moderate value.

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

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

The description clearly states it pulls fired events from the subscription feed with specific return fields. While it doesn't explicitly distinguish from sibling tools like list_subscriptions or recall, the verb 'pull' and focus on alerts versus subscriptions or general search is clear enough.

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

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

The description mentions filtering options and polling as a valid use case. It also points to an alternative HTTP endpoint. However, it lacks explicit guidance on when to use this tool versus siblings like search or recall, and doesn't specify when not to use it.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable behavior details: fan-out strategy, fallback from GDELT to GNews, soft-fail for USPTO, accepted date formats, and return structure.

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 fairly long but well-structured: starts with example queries, explains functionality, parameter details, return structure, and alternative tool. Every sentence adds value; could be slightly tighter but still effective.

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

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

Given complexity and lack of output schema, description is comprehensive. It explains return format (changes[] grouped by source, total_changes count, citation URIs), multiple data sources, fallback behavior, and failure mode for USPTO.

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

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

Schema covers 100% of parameters. Description adds extra use context like 'only "company" supported', relative date examples (7d, 30d, 3m, 1y), and suggestion to use '30d' or '1m' for typical monitoring.

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

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

Description clearly states it's a change feed for a company over a recent window, listing specific sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes from sibling 'entity_profile' 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 tells when to use this tool (dynamic changes) vs. entity_profile (static profile). Includes example queries that help the agent identify appropriate contexts.

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

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

Annotations already indicate idempotency (idempotentHint=true) and non-destructive behavior. The description adds context beyond annotations: scoping by identifier, persistence duration for authenticated vs anonymous sessions, which is valuable.

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

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

Four sentences, each essential: purpose, use case, storage details, related tools. Front-loaded with primary action, no redundancy.

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

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

For a write tool with no output schema, it explains persistence behavior and scoping. Could mention if key overwrites or return status, but given annotations and schema clarity, it's sufficiently 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 covers both parameters with descriptions (100% coverage), so baseline is 3. The description adds context about key-value pair and scoping, but no additional syntax or constraints beyond schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' and specifies it stores key-value pairs. It distinguishes from siblings by mentioning pair with recall and forget.

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

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

Explicit guidance is provided: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also references related tools for retrieval and deletion, though it doesn't explicitly list cases when not to use.

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

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

The description goes far beyond annotations (readOnlyHint, idempotentHint, etc.) by disclosing that the tool cascades through multiple lookup endpoints, replaces 2-3 manual lookups, and degrades gracefully when GLEIF or OpenFIGI are unavailable. It explains identifier sources and what happens when resolution fails (unresolved field). No contradiction with annotations; these details add significant behavioral context.

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

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

The description is relatively long but well-structured: starts with example queries, states the core purpose, then details supported types. Every sentence adds value, explaining sources, behavior, and limitations. It is front-loaded with the most critical usage guidance. Minor redundancy could be trimmed, but overall it 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?

Given the tool has no output schema and complexity in return values (multiple identifiers, sources, unresolved field), the description is remarkably complete. It explains what is returned for each type, the sources (EDGAR, GLEIF, OpenFIGI, RxNorm), graceful degradation, and that it replaces multiple manual lookups. The behavior is fully contextualized for the agent to understand expected results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples for the 'value' parameter (e.g., 'AAPL', '0000320193', 'ozempic') and clarifies accepted input forms for both entity types. It also explains the 'type' enum choices in depth, including the resolution logic for each. This enrichment moves the score above baseline but stops short of full formal documentation of all possible input variations.

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 resolves a name to canonical identifiers, with specific examples like 'What's the ticker for' and 'find the CIK for'. It distinguishes from sibling tools by positioning itself as the first step for name-to-ID resolution, and covers supported entity types (company, drug) with their respective identifiers. The verb 'resolve' plus resource 'entity' is specific, and the description provides rich detail beyond the title.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', giving clear when-to-use guidance. It provides example queries and explains what input formats are accepted. It doesn't explicitly state when not to use or contrast with sibling tools like entity_profile, but the context makes it implicit. A brief exclusion clause would push to 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. No contradictions with annotations.

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

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

Two sentences: first sentence states the core purpose, second expands on method and use case. Every sentence is informative, no wasted words. Well front-loaded.

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

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

Given no output schema, the description covers return format (ranked list with score, confidence, signal density), entity count constraints (2-8 from schema), and the probing mechanism. Completes the picture for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with all 4 parameters described. The description adds meaning by clarifying that the first entity is treated as the 'subject' for narrative and that context disambiguates common names, going beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using specific verb 'compare' and resource 'AI visibility'. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example question. It implies usage for comparing multiple entities, but does not explicitly state when not to use or mention alternatives like ai_visibility_check.

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

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

Discloses composite nature across two services, potential 5-30s delay on bundlephobia's first measurement, and that partial failures return sources_failed. Adds context beyond annotations (readOnly, idempotent). No contradiction.

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

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

Description is front-loaded with key composite concept. Each sentence adds value; no redundancy. Slightly long but justified by content.

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

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

Given no output schema, description thoroughly explains return values (summary block, advisories, links, alternative versions). Covers errors, limitations, and behavior, making it self-contained for a 2-param 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 descriptions for both parameters. Description adds default behavior for version (latest published) but otherwise offers no additional semantic value beyond schema.

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

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

Description clearly states composite check for npm packages covering deps.dev and bundlephobia, addressing decision 'should I add this package'. Distinguishes from individual services and siblings by being a single call.

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

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

Explicitly says use when agent asks about safety, popularity, size, or cost of adding a package. Notes limitations: NPM only in v1; other ecosystems use deps.dev directly. Also describes graceful degradation on partial failures.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds little behavioral context. It does not mention pagination behavior or result structure.

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 short but could benefit from more detail. It is concise but under-specified for a search tool with 5 parameters.

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

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

Given the tool has 5 parameters and an output schema, the description does not fully explain capabilities like supported filters or result ordering. It lacks completeness for a general search 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 60%; the description adds minimal meaning beyond the schema. For instance, 'query' and 'start' lack descriptions in both schema and 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 clearly states the tool searches datasets, files, and dataverses. However, it does not differentiate from sibling tools like 'search_within' or 'dataset', which may be more specific.

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

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

No guidance on when to use this tool versus alternatives. The description merely states what it does, without context such as 'use for broad cross-type searches'.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds crucial behavioral context: embedding model (BGE-base-en), similarity measure (cosine), window size (500-char overlapping), character cap (200K with truncation flag), and return format (passages with offsets and scores). 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 with a clear front-loaded purpose and logical flow from usage to technical details. It is slightly verbose with implementation specifics (e.g., model name, window size) that could be shortened without losing clarity, but overall efficient.

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

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

Given no output schema, the description adequately covers return format (passages, offsets, scores), constraints (200K cap), and a pairing suggestion. It addresses the tool's complexity fully, leaving no obvious gaps for an AI agent to misunderstand invocation or output.

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

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

Schema coverage is 100% with all parameters described. The description adds value by explaining the 'text' parameter's maximum length and truncation behavior, providing query examples, and noting the limit default. However, the schema already covers basic descriptions, so the added nuance is moderate.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the action ('search within'), the resource ('a fetched record'), and the scope ('INSIDE'). It distinguishes itself from sibling tools like 'search' and 'ask_pipeworx_grounded' by focusing on searching within an already-fetched record, making its purpose unambiguous.

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

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

The description explicitly advises use when a record is too large for the prompt and suggests pairing with 'ask_pipeworx_grounded'. However, it does not explicitly state when not to use or list alternative tools for smaller records, leaving some ambiguity.

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

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

Beyond annotations, the description adds substantial behavioral traits: requires OAuth account, specific subscription types, phone verification, daily SMS cap, webhook HMAC signing, and auto-disable after 10 failures.

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 paragraph packing a lot of information. It is front-loaded with the main action but could be structured more cleanly with bullet points.

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

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

Given no output schema, the description explains return value (subscription ID) and mentions webhook_secret. It covers the main points for a complex tool with nested params, lacking only a bit on error cases.

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

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

Schema already describes parameters with 100% coverage; the description adds extra context like phone verification requirement and daily cap, and delivery channel details not fully captured in 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 creates a monitoring subscription to a live-data event stream and returns a subscription ID. It uses specific verbs and resources, and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context about required OAuth account, supported types, and delivery channels, but does not explicitly state when not to use this tool or compare it to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by detailing the output structure (category-bucketed examples) and that it uses the live catalog, but does not contradict annotations.

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

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

The description is front-loaded with common query phrases, then provides detailed structure and usage. While slightly long, every sentence adds value and it is well-organized.

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

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

For an onboarding tool with no output schema, the description fully explains the return type (category-bucketed examples with tool/argument shapes) and covers usage variations. Nothing essential is missing.

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

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

Schema description coverage is 100% (one param with list of valid values). The description reinforces the optional topic parameter with examples, but adds limited additional meaning beyond the schema.

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

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

The description clearly states it returns category-bucketed example questions with tool+argument shapes, and positions it as the onboarding entry point. It distinguishes from siblings like ask_pipeworx by stating it's for when the agent doesn't know what Pipeworx can do.

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

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

Explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to use with/without topic. While it doesn't explicitly say when not to use, the 'first' implies it's a starting point before using other tools.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds that the row is deactivated (not deleted) and historical events remain accessible via 'recent_alerts'. This enriches understanding of the tool's side effects.

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 action and efficiently convey all necessary information without waste.

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

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

With a single parameter, no output schema, and annotations present, the description fully covers purpose, ownership, and deactivation behavior, making the tool's usage clear.

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

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

The schema already provides a description for the single parameter 'id' (100% coverage). The tool description does not add additional detail beyond stating 'by id', so it meets the baseline expectation.

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 ('Cancel a subscription by id') and resource ('subscription'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying cancellation behavior and ownership enforcement.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), which guides the agent on when this tool is appropriate. It does not explicitly state when not to use it, but context with siblings implies it's for cancellation only.

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

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

Goes well beyond the annotations. It discloses the two verification pipelines (SEC EDGAR fast path and grounded pipeline), the exact list of verdicts, the distinction between 'could_not_verify' and 'unsupported', and the error payload. It explicitly warns that 'could_not_verify' must not be treated as evidence, providing critical behavioral 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?

The description is long but every sentence earns its place. It is front-loaded with user-phrasing examples, then flows logically through purpose, routing, outputs, warnings, and efficiency benefits. No redundant or filler content.

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

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

Despite having no output schema, the description clearly enumerates return values (verdict list, grounded/structured value, citation, reasoning) and explains failure semantics. It covers edge cases, error taxonomy, and parameter behavior, making it fully complete for a tool with this complexity.

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

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

Schema coverage is 100%, but the description adds rich semantics: tolerance_pct is explained with range, override behavior, suggested values for hallucination detection, and default logic. The 'claim' parameter is clarified with realistic examples. This significantly enhances the schema definitions.

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

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

The description opens with natural-language query examples and clearly states the tool validates factual claims against authoritative sources. It distinguishes itself from siblings by emphasizing fact-checking and claim verification, with explicit routing 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?

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing details for company-financial vs. other claims. It also notes efficiency gains by replacing multiple sequential calls, giving clear invocation context.

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