Inspire Hep

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral details like scoring (0-100), default model, BYO key for Anthropic, and return structure. No contradictions.

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

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

The description is a single, well-structured paragraph with no wasted words. It front-loads the main action and then provides additional details in a logical order.

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 4 parameters, no output schema, and annotations providing safety traits, the description covers return values and usage context adequately. Some minor room for more on response format, but sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining default model for 'models' parameter and API key requirement, and clarifying the 'entity' parameter scope.

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

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

The description states the specific verb 'Probe' and resource 'LLMs' for scoring visibility, with clear applications like AI-marketing audits. It distinguishes itself from sibling tools by its unique function.

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: for AI visibility checks, and provides context on default model and API key usage. It does not explicitly contrast with siblings but gives clear usage scenarios.

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 value by explaining the tool routes to 3,899 tools, fills arguments, and returns pipeworx:// 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?

The description is verbose with multiple paragraphs and examples. While front-loaded with key instructions, it could be shortened without losing essential information.

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

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

Given no output schema, the description partially explains return format (structured answer with citations). It covers tier availability and when to use alternatives. Not fully detailed (e.g., error handling), but adequate for a read-only tool.

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

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

Schema description coverage is 100% with detailed descriptions and aliases. The description does not add significant new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool routes questions to authoritative sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, specifying when each is appropriate.

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 'PREFER OVER WEB SEARCH' and lists specific use cases (SEC filings, FDA data, etc.). It also provides guidance on when to use alternatives (grounded for verbatim evidence, deep_research for broad questions), making it easy for the agent to choose.

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, etc.), the description details routing, extraction-only, refusal reasons, and cost implication, fully disclosing behavior 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 comprehensive but well-structured with front-loaded purpose, then details and usage guidance. Slightly verbose but 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 no output schema, the description fully covers return structure (fields, refusal reasons), use cases, cost, and comparison to sibling. Complete for a complex tool.

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

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

Schema coverage is 100%, and the description clarifies aliases for the question parameter. While it adds modest value beyond the schema, it is helpful and does not repeat schema details.

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 a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling 'ask_pipeworx' by emphasizing its extraction-only behavior and refusal modes.

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 instructions on when to use (high-stakes, quoted/cited/acted on answers, must not invent facts) and when to prefer the sibling 'ask_pipeworx' for casual lookups, including cost trade-off.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds no behavioral context beyond what annotations provide, such as what happens if the ID is not found or the output format.

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 with no extraneous words, making it highly concise 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 output schema exists (not shown), the description need not detail return values. However, for a simple tool with one required parameter, it is adequate but could mention that the tool retrieves a full author record.

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 compensates by stating the parameter is an 'INSPIRE id', which adds meaning beyond the schema's 'number' type. However, it does not elaborate on format or validation.

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 'Author record by INSPIRE id' clearly indicates the tool retrieves a single author record using an identifier, distinguishing it from sibling tools like 'authors_search' which likely searches for authors. However, it could be more explicit with a verb like 'Fetch'.

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 is provided on when to use this tool versus alternatives such as 'authors_search' or 'entity_profile'. The description does not indicate prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which convey the tool's safe, idempotent nature. The description adds no behavioral context but does not contradict the annotations.

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

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

The description is very concise at 2 words. While not verbose, it is underspecified and does not earn its place by adding value.

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

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

Given that the tool has 2 parameters, an output schema, and rich annotations, the description is severely incomplete. It fails to explain the scope, behavior, or return format of the search.

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 2 parameters (query and size) with 0% description coverage. The description does not mention any parameters or their meaning, leaving the agent to infer from the schema alone.

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

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

The description states 'Search authors', which is a clear verb+resource pair. However, it does not distinguish from sibling tools like 'search' or 'literature', which might also search authors. The purpose is understood but lacks specificity.

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 is provided on when to use this tool versus alternatives. The description does not mention any context, prerequisites, or exclusions.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are complemented by extensive behavioral details in the description. It covers low-confidence resolution handling, closed/dead markets, wide spread warnings, resolution-rule risk, and news fallback mechanisms. 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 very long (approximately 700 words) and includes numerous details, examples, and edge cases. While comprehensive, it could be more concise. The structure uses paragraphs and bullet-like lists but front-loads key information about what the tool does.

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 (multi-source fan-out, classifiers, response shapes, error handling), the description is remarkably complete. It covers all major behavioral aspects, safety measures, and explains return fields in detail. No output schema exists, so the description carries the full burden, which it meets well.

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% (all three parameters have descriptions). The description adds value by providing examples of valid inputs for 'market', explaining the 'depth' enum, and detailing 'include_raw' behavior. This enhances understanding beyond the schema alone.

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

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

The description clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies accepted inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on specific 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?

Explicit usage examples are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description also instructs when to inspect fields like market_match_confidence before trusting analysis. However, it does not explicitly state when not to use this tool or mention alternatives by name.

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 beyond annotations by explaining the parallel call nature, data fields retrieved (revenue, net income, cash, debt for companies; adverse-event counts, approval counts, trial counts for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions with annotations.

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

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

The description is a single paragraph but well-structured: starts with example queries, then usage guidance, then detailed data behavior. While slightly lengthy, every sentence adds value. It is front-loaded with key information.

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

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

The description covers input, data retrieved, sorting, and output hints. Missing explicit output format details, but the mention of 'paired data + citation URIs' and 'sorted by primary metric' provides sufficient completeness for a comparison tool with no output schema.

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

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

Schema coverage is 100%, but the description adds significant context: for 'type' it details what data is pulled per enum value; for 'values' it specifies acceptable formats (tickers/CIKs for company, names for drug) and min/max. This enriches parameter understanding beyond the schema.

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

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

The description clearly defines the tool's function: side-by-side comparison of 2-5 companies or drugs. It uses specific verbs like 'compare' and provides example queries. The detailed explanation of data sources for each entity type (SEC EDGAR for companies, FAERS for drugs) and sorting behavior distinguishes it from other tools.

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

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

The description explicitly advises preferring this tool over sequential lookups when comparing entities, and lists concrete use cases ('which is bigger', 'rank these companies'). This 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 convey readOnly, openWorld, idempotent, and non-destructive behavior. The description adds no behavioral traits beyond stating a search operation, which is already implied by the name.

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 extremely concise (two words) but at the expense of informativeness. Every word should add value; here, only a generic verb and noun are present.

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 two parameters without schema descriptions and no usage guidance, the description is incomplete. It does not equip an agent to use the tool correctly without additional inference.

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 must explain parameter meaning, but it does not. The tool has two parameters (query, size) and the description gives no indication of their roles or expected values.

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

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

The description states 'Search conferences.' which is clear enough as a basic purpose but lacks specificity (e.g., what kind of conferences, scope) and does not distinguish from sibling search tools like 'authors_search' or 'institutions_search'.

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

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

No guidance is provided on when to use this tool versus alternatives, nor any exclusions or context. The description is too brief to offer usage guidelines.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds critical behavioral context: account requirement, paid plan for 'thorough' depth, parallel decomposition across 3,899 tools, return format (findings packet with evidence, confidence, source, gaps[]), expected time (15-60s), and behavior when topic is outside the catalog (empty gaps[]).

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

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

The description is somewhat lengthy but front-loads critical information (account required) and is well-structured. Every sentence adds value; the length is justified by the complexity of the tool. A minor trim could be made without loss.

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 (2 params, no output schema), the description is remarkably complete. It covers prerequisites, limitations, behavior, return format, timing, and clear alternatives. Agents have sufficient information to decide whether to invoke this tool.

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

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

Schema coverage is 100%, so parameters are already documented. However, the description adds value by explaining that the 'question' can be broad/multi-part and that 'depth' levels correspond to plan access (paid for thorough). This extra nuance slightly improves usability.

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

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

The description states the tool performs 'grounded multi-source research across Pipeworx's 932 STRUCTURED data sources', which is a specific verb-resource combination. It explicitly distinguishes from siblings like 'ask_pipeworx' by noting when that sibling is preferable.

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

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

The description provides explicit when-to-use ('best for broad/multi-part questions over structured data') and when-not-to-use ('for a single lookup use ask_pipeworx', 'for BREAKING or colloquial CURRENT-NEWS...prefer ask_pipeworx'). It names the alternative sibling tool and explains why.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds that it returns top-N tools with full schemas and examples, ready to call directly, which goes beyond annotations. 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: first states purpose, second lists domains and output features, third gives usage instruction. Front-loaded and efficient with no wasted words.

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

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

Despite lacking an output schema, the description fully compensates by detailing output format (names, descriptions, schemas, examples). Input parameters are all documented. No gaps given the tool's discovery purpose.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by clarifying that task, q, search, description are aliases for query, and explains that results include schemas and examples, which aids usage.

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

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

States 'Find tools by describing the data or task' with specific verb and resource, and includes a long list of domains (SEC filings, FDA drugs, etc.) that distinguishes it from sibling tools like search or deep_research which query data rather than discover 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 says 'Call this FIRST when you have many tools and want to see the option set (not just one answer)', providing clear when-to-use and avoiding misuse as a direct answer 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 declare read-only, idempotent, non-destructive behavior. The description adds detailed behavioral context: fan-out across multiple data sources, return fields (cik, filings, fundamentals, etc.), sorting of fundamentals, fallback mechanisms (GDELT→GNews), and patent API sunsetting with soft-fail. This goes well beyond the annotations.

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

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

The description is moderately long but each sentence serves a purpose: example queries, intended use, detailed return structure. It is front-loaded with user-facing examples. Could be slightly tighter but remains 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 no output schema, the description fully explains the return envelope: CIK, company name, recent filings (with URIs), fundamentals (with details), patents (with sunset note), news (with fallback), and LEI. It also covers constraints (US public company only) and data source specifics. Complete for an agent to understand behavior.

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

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

Schema coverage is 100% with descriptions. The description adds value by clarifying that 'value' can be a ticker or zero-padded CIK (with examples), and that 'type' is currently limited to 'company'. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides example queries, specifies the entity types supported, and distinguishes itself from chaining multiple tools by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' It also guides when to use a sibling tool (resolve_entity) for names.

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

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

The description explicitly states when to use this tool: when a user asks for a holistic view of a US public company. It also gives clear exclusion: 'Names not supported — use resolve_entity first if you only have a name.' The directive 'ALWAYS PREFER' guides selection over 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 provide destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data, but doesn't contradict annotations. The description supplements without redundancy.

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 concise sentences: action statement, usage guidance, and pairing recommendation. No wasted words, front-loaded with essential information.

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

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

Given tool simplicity (1 parameter, no output schema, clear annotations), the description fully covers purpose, usage, and behavior. No gaps remain for this low-complexity 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 clear description for 'key' parameter. Description merely says 'by key', adding no meaningful information beyond the schema. Baseline score of 3 is appropriate.

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

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

Clearly states 'Delete a previously stored memory by key', specifying verb (delete), resource (memory), and required parameter (key). Distinguishes from sibling tools 'remember' and 'recall' as the deletion counterpart.

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 scenarios: stale context, task completion, clearing sensitive data. Also recommends pairing with 'remember' and 'recall', guiding proper tool selection.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds details: fetches page, extracts title/description/key links, emits standard markdown. This goes beyond annotations, but could mention rate limiting or page size limits.

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

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

The description is concise, front-loaded with the main purpose, and each sentence adds value. No redundant information; it efficiently covers behavior and use cases.

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

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

Despite no output schema, the description explains the output format and purpose completely. It covers parameters, behavior, and use cases adequately for a simple tool with good annotations.

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

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

Schema coverage is 100%, so parameters are well-defined. Description adds default value for max_links (25) and clarifies the URL parameter's usage. This extra context elevates above baseline 3.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate) and resource (llms.txt). It distinguishes from siblings like scan_competitor_ai_presence by focusing on file creation, not just scanning.

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

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

The description lists specific use cases: getting a client's site indexed, drafting for own project, or auditing competitor. It implies when to use but does not explicitly exclude alternatives or mention siblings, though the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, indicating safe, read-only behavior. The description adds no behavioral details beyond what the annotations provide, but does not contradict them.

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

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

The description is extremely short (2 words) and fails to provide necessary detail. While concise, it is under-specified and does not earn its place by adding value beyond the tool name.

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 (2 parameters, 0% schema coverage, no output schema details in description), the description is severely incomplete. It lacks information on parameters, return values, and usage context.

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

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

With 0% schema description coverage, the description should explain parameter meanings. However, it says nothing about 'query' or 'size'. This leaves the agent guessing about expected input formats and constraints.

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

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

The description clearly states 'Search institutions', establishing the verb and specific resource. It differentiates from sibling tools like 'authors_search' and 'conferences_search' by targeting a distinct entity type, though no explicit distinction is made.

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 usage guidelines provided. The description does not indicate when to use this tool over alternatives like 'search' or 'authors_search', nor does it explain context or exclusions.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds the specific returned fields and the scope (the caller's subscriptions), which provides some additional context but does not significantly expand on the behavioral traits 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 concise, with only two sentences that are front-loaded. The first sentence defines the purpose and return fields, and the second provides usage guidance. No unnecessary words or 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 that the tool has a simple structure (one optional parameter, no nested objects, no output schema), the description is complete. It lists the return fields and provides usage context, which is sufficient for an agent to understand the tool's functionality and when to invoke it.

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

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

Schema coverage is 100% with a clear description of the 'include_inactive' parameter. The tool description does not add any additional meaning or context about the parameter beyond what the schema provides, so it meets the baseline but does not exceed it.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the returned fields (id, type, etc.). It also differentiates from sibling tools like 'subscribe' and 'unsubscribe' by indicating it is for reviewing existing subscriptions before adding or canceling.

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

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

The description provides explicit use cases: 'to review what you're monitoring before adding more or to find an id to cancel.' This gives clear guidance on when to use the tool, though it does not explicitly state when not to use it or mention alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds no additional behavioral context beyond what annotations provide. It is consistent and does not contradict.

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, front-loaded with the core purpose. It contains no extraneous information and is appropriate for a simple tool.

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

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

Given the tool's simplicity (1 parameter, read-only, with output schema), the description is nearly complete. It could mention what is returned, but the output schema likely covers that.

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 0%. The description does not explain the format, source, or constraints of the record_id parameter beyond what is evident from the schema type (number).

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

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

The description clearly states the tool retrieves a single literature record by INSPIRE record id. It uses a specific verb ('Single') and resource ('literature record'), and distinguishes from sibling tools like search or authors_search.

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

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

No guidance is provided on when to use this tool versus alternatives such as search or authors_search. The description lacks context about prerequisites or 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?

Beyond the minimal annotations, the description reveals important behavior: it is free, does not count against tool-call quota, is rate-limited to 5 per identifier per day, and that feedback is read daily and influences the roadmap. This fully informs the agent of consequences.

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 and well-structured: it starts with the core purpose, then gives usage scenarios, followed by a key formatting rule, and ends with behavioral notes. Every sentence adds value with no redundancy.

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

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

Given that there is no output schema and the tool is simple (3 parameters, one nested), the description covers all needed context: when to use, what to include in each parameter, rate limits, and that it's free. The agent can confidently invoke this tool without additional information.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra usage guidance for the 'message' parameter (don't paste end-user prompts) and reinforces the enum values, but does not add significant new semantics beyond the schema. Still, it provides practical context.

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

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

The description clearly defines the tool's purpose: to send feedback to the Pipeworx team about bugs, missing features, or praise. It distinguishes itself from sibling tools by focusing on communication with the team rather than performing data retrieval or analysis.

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

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

The description explicitly states when to use the tool (bug, feature/data_gap, praise) and provides a concrete instruction: describe the issue in terms of Pipeworx tools/packs, not the end-user's prompt. It also mentions rate limits and that it's free, guiding appropriate usage.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds 'self-aggregating signal, no PII, cached 5min-1h', providing valuable behavioral context beyond annotations.

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

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

Description is concise (4-5 sentences), front-loaded with core functionality, and uses clear bulleted use cases. No superfluous information.

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

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

Despite no output schema, description explains return values (top tools, packs, volume), data source, privacy, and caching. Fully covers what an agent needs to know for safe 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% (parameter 'window' described). Description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', which aids selection.

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

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

The description clearly states 'Returns the top tools, top packs, and total call volume over a recent window', specifying the exact resource and action. It distinguishes from siblings like 'discover_tools' and 'ask_pipeworx' by focusing on trending aggregation.

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

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

Three explicit use cases are bulleted: discovering hot data sources, confirming popular tools, and aligning use cases. It also mentions caching behavior. Lacks explicit 'when not to use' but context implies 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?

Beyond annotations (readOnly, idempotent, openWorld, not destructive), the description adds critical behavioral details: requirement of exactly one of event/topic, Jaccard similarity filter, placeholder partition filter, fill check logic, and response structure. These significantly aid correct usage.

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 sections but is quite verbose (over 350 words). Some details, like the fill check, could be streamlined. Front-loading the requirement statement is good, but overall length slightly hinders quick comprehension.

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

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

Given no output schema, the description fully explains the response fields (opportunities, partition_check, fill_check) and covers all major behaviors. It also references related tools for custom sizing, making it self-contained for the intended 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%, so baseline is 3. The description adds significant value by explaining the difference between event and topic modes, accepted formats (e.g., full URLs), and how each mode affects the analysis, elevating it above baseline.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection and partition logic.

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

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

The description explains when to use event vs topic modes and explicitly mentions 'For custom sizing use polymarket_fill_risk' as an alternative. However, it doesn't compare to other siblings like polymarket_edge_tracker or polymarket_kalshi_spread, leaving some usage ambiguity.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds rich behavioral details: three model families, caching at KV level (1h), diagnostic info, and tradeable-edge filters. No contradictions detected.

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

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

The description is lengthy but every sentence provides essential technical details. It is front-loaded with purpose and well-structured, though slightly verbose for the complexity it addresses.

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

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

Given the tool's complexity (9 parameters, no output schema), the description covers behavioral details, caching, diagnostics, and tradeable-edge knobs adequately. Some missing details about return value structure are compensated by the rich parameter descriptions.

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 9 parameters. The description adds extra context beyond the schema, such as explaining slippage, why min_kelly doesn't filter partitions, and the purpose of min_partition_leg_kelly. This adds value but does not significantly surpass the schema coverage.

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

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

The description explicitly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it is built for 'what should I bet on today'. This clearly distinguishes it from sibling tools like polymarket_arbitrage or other search tools.

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

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

The description provides clear context for when to use the tool ('what should I bet on today' and for discovering opportunities without paging). It explains the tradeable-edge knobs and filters but does not explicitly state when not to use it versus alternatives, leaving a minor gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds substantial behavioral context: uses daily snapshots (not real-time), computes decay on absolute edge_pp_net, describes output structure and limitations. 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 well-structured and efficient: front-loaded purpose, then output fields, then limits. Every sentence adds value, no fluff.

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

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

With no output schema, the description fully details the return structure (tracked, expired, snapshot_dates) including fields, trends, and decay computation. It also covers limitations and data gaps, making it comprehensive.

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 minor clarifications (defaults, days clamp, window meaning) but does not significantly extend 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: providing edge persistence and decay telemetry from daily snapshots. It specifies the resource (polymarket_edges snapshots) and the action (tracking edge age and trend). It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description provides context for when to use the tool, contrasting fresh vs old edges. It mentions limits (60-day TTL, snapshot gaps). However, it does not explicitly state when NOT to use it or suggest alternatives, which would have improved clarity.

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

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

Annotations provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds behavioral context: it walks the order-book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and warns about partial basket fills. It does not contradict annotations and provides additional transparency about risks and results.

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, starting with purpose, then modes, parameters, usage guidelines, and return fields. While it could be slightly more concise, every sentence adds value and it is not overly verbose. Front-loading is 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 complexity (two modes, four parameters, no output schema), the description is remarkably complete: it explains both modes in detail, lists explicit return fields, provides usage conditions and risks, and addresses edge cases like thin books and partial fills. No additional information is needed for an agent to understand and use the tool correctly.

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

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

Schema description coverage is 100%, and the description adds significant meaning beyond the schema: it explains how size_usd is interpreted differently in single-market vs basket mode, the auto-default for side in basket mode, and the distinction between market and event parameters. Examples further clarify usage.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes with specific examples, and the name 'polymarket_fill_risk' aligns well with this purpose. It is specific and differentiates from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly advises using this tool before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. It explains why (theoretical overround not capturable, partial baskets convert arb into unhedged directional positions) and 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 declare read-only, open-world, and idempotent. Description adds extensive behavioral context: compatibility_warning conditions (non-equivalent bet shapes, semantic mismatch), temporal alignment flag, and skipped leg reasons (cross-type/cross-subtype). 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?

Well-structured with clear sections (modes, response, safety fields). All sentences are informative, though some explanations (e.g., compatibility_warning details) are verbose. Could be slightly more concise without losing value.

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

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

Despite no output schema, description fully explains the response and handles edge cases (temporal alignment, skipped comparisons). With 3 optional parameters and no required ones, the description is remarkably complete.

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

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

Schema coverage is 100%, but description adds meaning beyond schema: explains topic values, override behavior, and response structure (leg-by-leg prices, top_spreads_pp). Enriches understanding without being redundant.

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?

Title and description clearly state it computes cross-venue spread between Kalshi and Polymarket for the same question. Specifies two modes (topic and explicit), response structure, and safety fields. Distinguishes from siblings like 'polymarket_arbitrage' by focusing on cross-venue spread and noting most pre-mapped topics return compatibility warnings.

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

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

Provides explicit guidance on when to use each mode, and when spreads are meaningful vs not (compatibility_warning cases, temporal alignment). Warns that pre-mapped topics often yield warnings, setting realistic 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 provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds scoping and examples but does not significantly extend beyond annotations. 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 concise with four sentences, front-loaded with action, and no wasted words. Efficiently communicates purpose, usage, scoping, and relationships.

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?

Completeness is high given the optional parameter and clear annotations. However, lacks description of return format (e.g., string or list) when listing keys, which is a minor gap.

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 retrieve (omit to list all keys)'. Description reinforces this but adds no new semantic meaning. Baseline 3 applies.

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

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

The description clearly states the tool retrieves a saved value or lists keys, with specific verb 'retrieve' and resource 'value previously saved via remember'. It distinguishes itself from siblings 'remember' and 'forget' and provides concrete examples like ticker, address, notes.

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

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

Explicitly states when to use: 'look up context the agent stored earlier' and 'without re-deriving it from scratch'. Mentions scoping and pairing with remember/forget. Lacks explicit 'when not to use' but context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds behavioral details: mark_read effect on subsequent calls, returned fields (source, citation_uri, raw payload), and alternative access method.

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 (4 sentences) and front-loaded with the action. 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 no output schema, the description adequately covers return fields and provides alternative access. Missing some parameter details but overall sufficient for a read-only tool.

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

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

Schema coverage is 100% (baseline 3). Description enhances understanding by explaining usage of type, since, and mark_read parameters beyond schema descriptions, though limit and unread_only are not explicitly discussed.

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

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

The description clearly states the tool pulls fired events from the user's subscription feed, returning specific fields. It distinguishes from sibling tools like list_subscriptions by focusing on alert 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?

Provides guidance on filtering by type/since, using mark_read, and notes polling is fine. Offers an alternative URL. Lacks explicit comparison to other tools but covers key usage context.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses key behaviors: fans out to multiple sources (SEC, GDELT/GNews, USPTO), fallback logic (GDELT preferred, GNews on rate limit), soft-failure for USPTO, and return structure (changes[] grouped by source, total_changes count, citation URIs). No contradictions with annotations.

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

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

The description is fairly long but every sentence adds necessary context. It is front-loaded with query examples and uses clear structure (hyphens for sources). Could be slightly more compact, but remains readable and informative.

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

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

Given the complexity (multiple sources, fallback, output structure) and no output schema, the description provides a comprehensive overview. It explains what the tool does, when to use it, parameter details, and what is returned. However, it could explicitly mention that the output is a JSON 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 coverage is 100%, but the description adds practical value: explains `since` formats (ISO date vs. relative shorthand with examples), typical usage, and notes that `type` only supports 'company'. This supplements the schema descriptions effectively.

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: 'change feed for a company in the last N days/weeks/months' with example queries like 'What's new with X' and distinguishes it from the sibling tool 'entity_profile', which is for static profiles. The purpose is specific and 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?

Explicit guidance is provided: when to use this tool (for recent changes) and when to use an alternative ('Use entity_profile instead when you want the static profile regardless of window'). Also includes example queries and typical parameter values ('Use "30d" or "1m" for typical monitoring').

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

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

Annotations provide idempotentHint=true and destructiveHint=false. Description adds critical context: scoping by agent identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. No contradiction with annotations.

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

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

Three well-structured sentences: first states purpose, second gives usage guidance, third adds behavioral details. No wasted words, front-loaded with core action.

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 only 2 parameters, no output schema, and good annotations, the description fully covers purpose, usage, behavior, and parameter semantics. No gaps for the agent to infer.

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

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

Schema coverage is 100% with adequate descriptions for key and value. Description adds value by explaining the key-value nature and providing examples of what to store, going slightly 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 with specific verbs and resource: 'Save data the agent will need to reuse later' as a key-value pair. It effectively distinguishes from siblings by naming recall and forget as complementary tools.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward' with concrete examples (ticker, address, preference, research subject). Also notes pairing with recall/forget. Lacks explicit when-not-to-use, but is sufficiently clear for an agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details: the tool cascades through multiple endpoints internally, replacing 2-3 manual lookups, and specifies return values for each type including citation URIs.

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 yet comprehensive, front-loaded with example queries and structured as a clear paragraph with bullet-like details for supported types. Every sentence adds value without redundancy.

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

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

Given no output schema, the description fully explains return values for each entity type (including citation URIs). It covers auto-disambiguation and the internal cascading behavior, making the tool's behavior transparent despite lacking an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples for the 'value' parameter (ticker, CIK, name; brand/generic drug) and clarifying the enum options for 'type', making parameters more actionable.

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

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

The description uses specific verbs like 'resolve' and 'look up', names the resource (canonical/official identifier), and explicitly states the purpose for each entity type. It distinguishes itself from siblings by stating 'Use FIRST whenever you have a name but need an ID.'

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

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

The description provides clear when-to-use guidance ('Use FIRST whenever you have a name but need an ID.') and lists supported types with examples. It does not explicitly state when not to use, but the context is sufficient for most agents.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing the process (probes each entity with ai_visibility_check, ranks by score) and output (ranked list with score, confidence, signal density), which goes beyond annotation hints.

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, using three sentences that front-load the purpose and follow with usage context and return details. Every sentence adds value without redundancy, making it efficient for an agent 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?

Despite lacking an output schema, the description clearly states the return format (ranked list with score, confidence, signal density) and the process (probes, ranks). For a tool of moderate complexity with full parameter schema coverage, the description is self-sufficient and provides adequate context for correct invocation.

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

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

Schema coverage is 100%, providing clear per-parameter descriptions. The description adds context beyond the schema by explaining that the first entity is treated as the subject and that context disambiguates common names, enhancing understanding for effective use.

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 verbs (compare, probe, rank) and resources (AI visibility, entities). It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on competitive AI-marketing audits.

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 ('does Claude know about us as well as our competitors?') and context (competitive AI-marketing audits). However, it does not explicitly mention when not to use this tool or name alternative siblings for single-entity checks, though the multi-entity focus implies when it's appropriate.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds critical behavior: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. This aids agent expectation management and error handling, and 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 information-dense but every sentence adds value: core purpose first, then data sources, usage hint, return fields, ecosystem limitation, and failure behavior. No fluff, front-loaded, 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 tool's complexity (two external services, partial failures) and absence of output schema, the description thoroughly lists return fields, failure modes, and ecosystem scope. It lacks explicit format of per-advisory details, but overall provides sufficient context for an agent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds minor context (scoped packages accepted, version defaults to latest) but does not significantly expand beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a composite check for evaluating whether to add an npm package, combining deps.dev and bundlephobia data. It specifies the verb 'scan', the resource (npm packages), and distinguishes from sibling tools like 'search' or 'validate_claim' by its unique multi-source aggregation.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes the ecosystem limitation (NPM only in v1) and directs users to deps.dev:version for other ecosystems, providing clear when-to-use and when-not-to-use instructions.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. Description adds no additional behavioral traits (e.g., result limits, rate limits, or data sources). Agent gains no extra insight beyond structured metadata.

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

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

Extremely brief (two words) but under-specified. While front-loaded, it sacrifices necessary detail. The description should include more context without being 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 rich schema and output schema, the description omits critical context: sources indexed, result format, and how this 'literature' search differs from others. Incomplete for effective agent selection.

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

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

Schema covers all parameters with descriptions at 100% coverage. Description does not add further meaning, but baseline is maintained as schema handles the documentation burden adequately.

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

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

Description 'Literature search.' adds only slight specificity beyond the name 'search'. It does not differentiate from sibling tools like 'literature' or 'search_within', and lacks details on scope or resource.

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 vs alternatives such as 'authors_search' or 'search_within'. The description fails to provide context for selection among many sibling tools.

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

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

Annotations already indicate safe read operation (readOnlyHint, idempotentHint, not destructive). Description adds rich details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings over 500-char windows, caps input at 200K chars with truncation flag.

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 6 sentences, each serving a clear purpose: purpose, usage scenario, pairing, technical details (embedding, windows, caps). No fluff, 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?

No output schema exists, but description adequately explains return format (passages with offsets and scores) and behavior under truncation. Sufficient for a tool with 3 simple 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 descriptions, but the description adds value by explaining the embedding model, windowing strategy, and giving query examples. This enhances understanding beyond the schema alone.

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

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

Description clearly states it performs semantic search inside a fetched record, using specific verb 'search' and resource 'inside a record'. It distinguishes itself from siblings like 'search' and pairs with 'ask_pipeworx_grounded' for grounded responses.

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

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

Explicitly says to use when the record is too big for the prompt, saving context. Mentions alternative pairing with 'ask_pipeworx_grounded'. The context is clear even if it doesn't explicitly list 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 adds significant behavioral context beyond annotations: OAuth requirement, sms cap of 10/day, webhook signing secret returned only once, and auto-disabling after 10 failures. Annotations already indicate it is not read-only and is idempotent, and the description aligns.

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 that front-loads the core purpose, but it is lengthy due to needed complexity. Structure could be improved with bullet points, but the information 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?

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers return value (subscription id), all parameter details, delivery options with constraints, and provides examples for each subtype. It is fully informative.

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

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

Schema coverage is 100%, but the description enriches each parameter with examples and constraints (e.g., type enum explained with specific uses, params format per type, delivery channel details and restrictions).

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

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

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

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

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

The description provides context such as requiring a Pipeworx OAuth account and lists supported types with examples. It implicitly guides when to use (to subscribe to alerts) but does not explicitly state when not to use or suggest alternative tools.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds that it returns exact tool+argument shape from the live catalog and that no arguments gives full spread. This adds value beyond annotations.

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

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

The description is somewhat long but well-structured with examples and explicit instructions. It is front-loaded with common query phrases and efficiently conveys 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 no output schema, the description fully explains the return value (categorized examples with tool shapes) and usage. It covers what the tool does, how to call it, and when to use it, leaving no gaps.

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

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

Schema coverage is 100% with one parameter described. The description adds the list of acceptable topic values and explains the effect of omitting the parameter, providing 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 explicitly states the tool returns category-bucketed example questions and positions it as the onboarding entry point. It uses specific verbs and resource, and distinguishes from sibling tools by indicating it is the first tool to use when unsure.

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 says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains passing a topic to focus. While it doesn't explicitly state when not to use, 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?

Adds ownership constraint and deactivation semantics beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). Rich behavioral context.

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

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

Two concise sentences, front-loaded with action and key constraints, no wasted words.

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

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

For a single-parameter tool with no output schema, description fully covers behavior, ownership, and persistence semantics.

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

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

Description references 'by id' but adds no new semantics beyond the schema, which has 100% coverage. Baseline score.

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 explicitly states 'Cancel a subscription by id.' Clearly distinguishes from sibling 'subscribe'.

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?

Mentions ownership enforcement and deactivation behavior, providing clear context. No explicit when-to-use vs alternatives, but context is strong.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds beyond annotations by detailing the verdict types (confirmed, refuted, etc.), return of structured form, actual value with citation, and percent delta. It also clarifies the data source (SEC EDGAR + XBRL). 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 somewhat long but well-structured, front-loaded with user intent examples. Every sentence provides useful information: domain, use case, benefits. Could be slightly more concise, but effective for an AI agent.

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

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

Given the tool has one simple parameter and no output schema, the description comprehensively covers input expectations, return types (verdict, structured form, citation, delta), domain, and data sources. It is fully adequate for correct invocation.

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

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

The input schema has one parameter 'claim' with a good description. Schema coverage is 100%, so baseline is 3. The description adds significant value by providing examples ('Apple's FY2024 revenue was $400 billion') and explaining the natural-language nature, which enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, specifically company-financial claims. It lists multiple example user intents ('Is it true that...', 'fact check', etc.) and specifies the domain (public US companies via SEC EDGAR + XBRL), making it highly specific and distinct from siblings.

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

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

The description explicitly says to use when the agent needs to check factual correctness of a user's statement. It mentions efficiency gains by replacing multiple sequential calls. However, it does not provide explicit when-not-to-use or alternative tools guidance, though the domain specificity implicitly limits usage.

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