Data Gov In

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, and not destructive. Description adds value by explaining the optional Anthropic key (BYO key, paid directly to Anthropic) and the return format (per-model fields + combined view). Does not mention rate limits or response times, but these are less critical given 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?

Four sentences, each serving a distinct purpose: function, default+optional, return format, use cases. No redundant words. Front-loaded with the primary 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 no output schema, the description provides the output shape ({score, confidence, signals, raw_response} + combined view). It explains the optional Anthropic integration and use cases. However, it does not elaborate on what 'signals' or 'confidence' mean, or how scoring works, which would be helpful for deeper understanding.

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 extra meaning by clarifying default model behavior and the role of _apiKey in Anthropic probing, and by stating the return format. This goes slightly beyond the schema descriptions.

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

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

Description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score per model. It specifies the default model and optional Anthropic integration, and lists concrete use cases. Suffices to distinguish from siblings like scan_competitor_ai_presence by focusing on general visibility scoring rather than competitor-specific 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?

Explicitly identifies three use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), giving clear context for when to use. However, does not mention alternatives or when not to use, nor differentiate from similar siblings such as scan_competitor_ai_presence or entity_profile.

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

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

Annotations already declare readOnlyHint true, openWorldHint true, idempotentHint true, and destructiveHint false. The description adds context about internal routing to 3,767 tools and citation URIs, which is helpful but not contradictory. It does not discuss rate limits or failure modes, but annotation coverage is sufficient.

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

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

The description is front-loaded with the key directive 'PREFER OVER WEB SEARCH', followed by a concise list of data domains, then usage triggers and examples. Every sentence contributes value without redundancy, and the structure is logical 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?

Despite no output schema, the description explains the tool returns structured answers with citations. It covers when to use, what it does, and provides examples. It does not detail error handling or what happens if no tool matches, but for a routing tool this is adequate given the complexity.

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

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

Schema description coverage is 100%: all six parameters are documented as aliases for the 'question' string. The description reinforces that the input is a natural language question and provides examples, but does not add new semantics 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 explicitly states it is preferred over web search for factual questions about specific data types (SEC filings, FDA data, etc.), clearly distinguishing it from general web search and sibling tools. It provides a specific verb ('ask') and resource ('Pipeworx'), with concrete examples.

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

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

The description strongly advises preference over web search and lists when to use (factual questions, given trigger phrases). It does not explicitly exclude cases, but the positive guidance is clear and specific. Sibling tools like 'ask_pipeworx_grounded' are not directly compared, but the comprehensive routing coverage is mentioned.

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

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

Description adds significant behavioral context beyond annotations: details the inner process (same routing as ask_pipeworx, tool selection, argument filling, data fetch, extraction using only tool result), describes the return structure with refusal reasons, and notes the cost of an extra LLM call. No contradiction with annotations.

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

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

Description is 5 sentences, front-loads key points, and every sentence provides value. Could trim minor redundancy (e.g., 'Accepts query, q, prompt, text, input as aliases' repeats schema), but overall efficient and well-structured.

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

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

Despite no output schema, the description fully details the return JSON structure including refusal reasons and fields. It explains behavior under success and failure conditions, covers 6 parameters (all aliases), and the sibling list provides adequate context. The description compensates fully for structured field 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 all 6 parameters described as aliases for 'question.' The description restates that aliases are accepted but adds no new semantic information beyond what schema provides. Baseline 3 is appropriate as schema handles the burden.

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

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

The description clearly states the tool as a 'hallucination-resistant answer mode' for high-stakes reads, specifies it extracts answers only from tool results, and distinguishes from its sibling 'ask_pipeworx' by noting the extra LLM call cost. The verb 'asks' is implied but the purpose is unambiguous and differentiated.

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 provided: 'Use whenever an answer will be quoted, cited, or acted on' with examples, and 'prefer ask_pipeworx for casual lookups.' This gives clear when-to-use and when-not-to-use context, contrasting with the sibling 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?

The description extensively details behavioral traits beyond annotations: market resolution, classification, parallel fan-out, response shapes, resolver contract, safety mechanisms (e.g., low-confidence short-circuit, closed market handling), wide-spread tradeability, and resolution-rule risk. Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent and enhanced by the description.

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

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

The description is long but well-structured with clear headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the purpose and uses cases. While verbose, each section provides essential detail for correct tool usage. Slightly lacking in conciseness due to length.

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

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

No output schema exists, so the description must explain return values. It does so thoroughly: result.market, result.analysis, result.evidence, resolver contract fields, parent event extractor, news fields, and error states (low_confidence_match, market_closed_or_inactive). The description is complete for a complex research tool.

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

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

Schema description coverage is 100%, but the description adds significant meaning: 'market' accepts slug, URL, or question text; 'depth' explains quick vs thorough with default; 'include_raw' describes behavior (summarized vs full payloads). This exceeds the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (Research), resource (Polymarket bet), and action. It also distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on researching a specific bet with comprehensive data.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples of fan-outs for different bet types and mentions when the tool short-circuits (low-confidence matches, closed markets). However, it does not explicitly state when not to use it compared to siblings, though the use cases are 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, open-world, idempotent, non-destructive. Description adds specifics: pulls 10-K data with correct fiscal year handling, FAERS counts for drugs, sorted results, 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?

Concise at 6 sentences, with key information front-loaded. No fluff, each sentence provides distinct value such as alternative phrasings, usage priority, data sources, and sorting behavior.

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

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

For a tool with no output schema, description adequately explains what is returned (paired data, citation URIs) and how results are sorted. Covers both entity types comprehensively. No gaps identified.

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

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

Schema coverage is 100%, but description enriches: gives examples for 'values' parameter (tickers/CIKs for companies, drug names for drugs), explains what data each 'type' returns, and clarifies the min/max count. Adds actionable guidance.

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

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

Clear verb 'compare' and resource 'entities' with specific descriptions of use cases like 'X vs Y', 'rank these companies'. Distinguishes from sibling tools like entity_profile which likely handles single entity lookups.

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

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

Explicitly states to prefer this tool over sequential single-pack lookups when comparing entities. Provides context for when to use by listing example queries and noting it replaces many sequential lookups.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds behavioral traits: decomposition into sub-questions, parallel routing to 3,770 tools, return of structured findings with evidence, confidence, source, and explicit gaps for unanswered facets. Also discloses expected latency (15-60s) and that facts are pre-verified.

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 concise and front-loaded with the core value proposition. However, it includes some extraneous details (e.g., 'sign in via GitHub at https://...') which could be shortened. Still, most sentences are necessary.

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

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

Given the tool's complexity (multi-source, parallel, 3770 tools), no output schema, but description fully explains return format (findings packet with evidence, confidence, source, fetched_at, citation, gaps). Also covers prerequisites and limitations. Complete enough for an agent to understand capabilities and expectations.

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

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

Schema coverage is 100% with both parameters described. Description adds meaning: explains depth enum values (quick=3, standard=5, thorough=8) and clarifies that question can be broad/multi-part. Adds value beyond the schema.

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

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

The description clearly states the tool performs 'grounded multi-source research in ONE call' with decomposition and parallel routing. It distinguishes itself from sibling tool ask_pipeworx, which is for single lookups. The verb 'research' and resource 'multi-source' are specific.

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

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

Explicit guidance: 'Use for broad or multi-part questions' and 'use ask_pipeworx for single lookups'. Also mentions prerequisites (Pipeworx account) and limitations (depth:thorough requires paid plan). Provides clear context on when to use vs alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: returns top-N tools with full schemas and curated examples, 'each result is ready to call directly, no second schema lookup needed.' No contradiction with annotations. This adds behavioral insight beyond the annotations without repeating 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 a single paragraph of about 5 sentences, front-loading the core purpose. It is efficient and informative, with no redundant phrasing. However, it could be slightly more concise by removing the list of domains (though that list adds context). Overall, it earns its place 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?

Given the tool has 6 parameters (with aliases), annotations, and no output schema, the description adequately explains the return format (top-N tools with schemas) and when to call it first. It is complete enough for an agent to understand the tool's role. A minor gap is not explicitly mentioning the default limit (20) or max (50), but the schema 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 100% (all 6 parameters have descriptions). The tool description mentions only the 'query' parameter conceptually and provides examples in the schema's 'examples' field. It does not add new semantic meaning beyond the schema descriptions. Per guidelines, when schema coverage is high (>80%), baseline is 3, which is appropriate here.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It enumerates supported domains (SEC filings, financials, etc.) and specifies the output (top-N relevant tools with names, descriptions, and schemas). It also distinguishes itself from siblings by advising 'Call this FIRST when you have many tools and want to see the option set.' This provides a specific verb-resource pair with clear differentiation.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools.' It implies that other sibling tools are for specific tasks, but does not explicitly exclude cases or name alternatives. This is clear context, but missing explicit 'when-not-to-use' or alternative tool references.

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, destructiveHint. Description adds behavioral details: fans out across multiple sources, soft-fails for USPTO patents, returns specific data fields with limits (up to 5 filings). 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 that efficiently packs information: example queries, purpose, data sources, return fields, and limitations. While not overly long, it could be more structured with bullet points. However, every sentence adds value.

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

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

No output schema, but description details all return fields (cik, filings, fundamentals, patents, news, LEI) and explains data sources and failure modes. For a tool with 2 parameters and high schema coverage, the description fully compensates for missing 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 has 100% coverage for both parameters. Description adds example values ('AAPL', '0000320193'), explains that names are not supported (use resolve_entity), and clarifies the enum limitation (only 'company' supported). This adds significant meaning beyond the schema.

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

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

Description starts with example queries and clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes from 'chaining single-pack SEC/XBRL/news lookups' and lists specific data sources and return fields. The purpose is highly specific with verb+resource+scope, differentiating it from siblings like resolve_entity.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also instructs to use resolve_entity if only a name is available, providing clear when-to-use, when-not-to-use, and alternatives.

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

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

Annotations indicate destructive and idempotent behavior. The description adds context about clearing stale or sensitive data, but doesn't mention error handling (e.g., key not found) or irreversibility beyond what annotations imply.

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

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

Two sentences, no wasted words. Purpose is front-loaded, and usage guidance follows succinctly.

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

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

For a simple tool with one parameter and no output schema, the description is largely complete. Could be improved by noting permanent deletion, but annotations already cover destructiveness.

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

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

Schema covers the single parameter 'key' with a clear description. The tool description does not add extra details 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 action ('Delete a previously stored memory by key') and distinguishes it from sibling tools like 'remember' and 'recall' which store and retrieve memories.

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 this tool: when context is stale, task is done, or to clear sensitive data. Also mentions pairing with 'remember' and 'recall'.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description complements by explaining it fetches the page, extracts content, and emits markdown. No contradictions, and additional context about output format is provided.

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

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

The description is concise at 4 sentences, front-loading the key action and output. Every sentence adds value without redundancy.

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

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

Given the simple 2-parameter tool with no output schema, the description fully covers purpose, behavior, output format, and use cases. It is complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, with both parameters (url and max_links) having clear descriptions. The description does not add extra meaning beyond the schema, which meets the baseline but doesn't 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 the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate) and resource (llms.txt file). It explains the process (fetches, extracts, emits) and distinguishes use cases from siblings like ai_visibility_check.

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 (getting a client's site indexed, drafting for own project, auditing competitors). However, it does not mention when to avoid using it or suggest alternative tools, leaving some room for improvement.

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 complements these by specifying that it returns active subscriptions by default (with include_inactive parameter) and detailing the returned fields. No contradictions.

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

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

The description is extremely concise: two sentences that front-load the primary purpose and then provide usage context. Every sentence adds value with no extraneous words.

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

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

The description is complete for a read-only list tool: it names the resource, lists return fields, explains the default behavior, and provides usage context. With full annotations and 100% schema coverage, no additional information is needed.

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

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

Schema coverage is 100%, so the schema already documents the one parameter (include_inactive). The description implicitly reinforces that it lists active subscriptions by default, aligning with the parameter default, but adds no new parameter-specific meaning beyond what the schema provides.

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

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

The description clearly states it lists the caller's active subscriptions and enumerates return fields (id, type, params, created_at, last_fired_at, fire_count). It is easily distinguished from sibling tools like subscribe and unsubscribe, but does not explicitly differentiate from other list-type 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 provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context for when to use it, but does not mention when not to use it or 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 are sparse (readOnlyHint=false, etc.), but the description adds important behavioral context: rate-limited to 5 per day, free, and doesn't count against tool-call quota. It does not describe destructive side effects, but since this is a feedback tool, none are expected. The description compensates well for the lack of annotation detail.

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: starts with the purpose, then usage guidance, then constraints. No extraneous words, every sentence adds value. Properly front-loaded.

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

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

Given the tool's simplicity (no output schema, few parameters), the description covers all necessary aspects: what it does, when to use it, how to structure the input, and limitations (rate limit, free). It is fully self-contained and leaves no ambiguity for an AI agent.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: it explains the enum values in context, advises on message specificity (1-2 sentences, 2000 chars max), and instructs not to paste end-user prompts. This helps the agent use the parameters correctly.

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

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

The description clearly identifies the tool's purpose: to send feedback to the Pipeworx team about bugs, features, data gaps, or praise. It uses specific verbs like 'Tell' and distinct categories, making it stand out from sibling tools which are primarily data retrieval or analysis 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 explicit guidance on when to use each feedback type (bug, feature, data_gap, praise), what to include in the message, and what to avoid (e.g., not pasting user prompts). It also mentions rate limits and that it doesn't count against quota, helping the agent decide when to invoke this tool instead of others.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. Description adds valuable context: self-aggregating from CF analytics-engine, no PII, cached 5min-1h depending on window. No contradictions.

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

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

Description is concise and well-structured: a one-sentence summary followed by three bullet-point use cases and a note on data source and caching. No wasted words.

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

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

Despite no output schema, the description explains return values (top tools, top packs, total call volume) and mentions caching. It covers the essential aspects for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by contrasting shorter vs longer windows ('shorter windows surface what's hot right now; longer windows show steady-state demand'), going beyond the schema's enum descriptions.

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

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

Description clearly states the tool returns trending tools, packs, and call volume with window options. The use cases differentiate it from siblings like discover_tools or ask_pipeworx, making the purpose specific and distinct.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tool, aligning use case). Does not mention when not to use or compare directly to alternatives, but the guidance is clear and useful for an AI agent.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds substantial behavioral context: parameter requirements, partition check logic, semantic anchor (Jaccard threshold), partition filter for placeholders, fill check with realizable edge vs theoretical edge, and custom sizing reference. 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: requirement, purpose, mode details, additional filters, response format, fill check. Front-loaded with critical requirement. Slightly verbose but each sentence adds value; could be trimmed slightly.

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 explains the response structure (opportunities array with gap_pp, suggested_trade, etc., and partition_check in event mode). Also covers fill check and links to a related tool for custom sizing. Comprehensive for the complexity.

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

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

Schema has 100% coverage for both parameters, but the description adds significant meaning beyond schema: explains the mode-specific behavior, how event mode walks child markets and checks ordering, how topic mode searches related events and flattens markets, and the fill check for event mode. This greatly aids agent selection.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between two modes (event and topic), provides specific examples of slugs and seed questions, and differentiates from sibling tools like polymarket_edges, polymarket_fill_risk, etc.

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

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

Explicit guidance on when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. Mentions that call requires exactly one parameter. Does not explicitly state when not to use or alternative tools, but the guidance is clear and actionable.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) are fully aligned with the description's read-only nature. The description adds substantial behavioral context: KV-level 1h caching, response structure (by_segment, diagnostics), and explanation of edge calculations. No contradiction.

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

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

The description is extremely verbose with multiple paragraphs and detailed model family explanations. While informative, it could be more concise; vital tradeable-edge knob info appears later, not front-loaded. The structure is coherent but too long.

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

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

Despite no output schema, the description thoroughly explains return fields (by_segment, fed_candidates, diagnostics) and per-opportunity attributes (edge_pp_net, kelly_fraction, liquidity, spread, 24h-move warning). It also covers caching and filter rationale, making it highly 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%, and the description adds meaningful context for most parameters (e.g., min_kelly skips small opportunities, slippage_pp includes use-case guidance). Some parameter explanations are buried in lengthy model details, but overall they add value beyond schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, distinguishing it from siblings like polymarket_arbitrage and polymarket_kalshi_spread. It also explains the three model families, solidifying purpose.

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

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

The description provides explicit usage context ('what should I bet on today') and guides parameter tuning via tradeable-edge knobs. It does not explicitly state when not to use, but offers implicit guidance through model family descriptions and diagnostic fields.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable context: snapshots written on cache-miss, decay from daily closes not intraday, response structure with tracked/expired arrays. 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?

Well-structured: starts with core purpose, then details behavior and response, ends with limitations. Every sentence adds value; no fluff despite length.

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

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

No output schema, but description fully explains response structure (tracked, expired, snapshot_dates) with field semantics. Covers edge cases (gaps, expiration) and limitations (TTL, start date). Sufficient for agent to understand outputs.

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

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

Schema covers 100% of parameters. Description adds default values, clamping bounds (max 30), and clarifies 'window' as snapshot family. Extends schema meaning beyond bare descriptions.

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

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

Clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. Uses specific verbs like 'Answers how long... and is it shrinking?' and distinguishes from sibling polymarket_edges by noting it builds on those snapshots.

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 context for when to use (for time-series edge analysis) and limitations (history depth, snapshot gaps). Does not explicitly name alternatives or when not to use, but the context is clear enough for an AI agent to differentiate.

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, destructiveHint false. The description adds significant detail beyond annotations: it specifies required parameters for each mode, explains return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about forced_directional_risk. No contradiction with annotations.

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

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

The description is long (about 200 words) but well-structured with mode sections. Every sentence adds value, covering purpose, usage, parameters, and return values. Could be slightly tighter, but no redundant information; it's dense and front-loaded.

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

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

The tool has two modes with complex behavior and no output schema. The description compensates fully by listing return fields for each mode, explaining the verdicts, and highlighting risks (thin books, directional risk). It covers all necessary context for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, but the description adds meaning beyond the schema. For example, it explains size_usd interpretation differs by mode (basket as settlement notional), side defaults vary by mode, and market/event accept slug or URL. This contextualizes parameters beyond the schema definitions.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It uses specific verb 'check' and resource 'fill risk', differentiating it 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?

Explicitly recommends using this tool 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial baskets become directional). This provides clear when-to-use and when-not-to-use guidance with rationale.

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 detailing safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/cross_subtype) and explaining when spreads are invalid. It does not contradict annotations; readOnlyHint and idempotentHint are consistent.

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

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

The description is thorough but somewhat long. It is well-organized, starting with purpose, then modes, response, and safety fields. Every sentence adds value, but a slightly more concise version could improve readability.

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

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

Given the tool's complexity (no output schema, 3 parameters), the description is highly complete. It explains the response structure, safety fields, and caveats for meaningful spread computation, leaving no critical gaps.

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

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

Schema coverage is 100%, and the description adds meaning about parameter interactions (override logic) and provides examples. It adds context beyond the schema's property descriptions, enhancing usability.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings by focusing exclusively on spread, not on single-venue data or arbitrage opportunities.

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

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

The description explains two modes (topic shortcuts and explicit pairings) and when spreads are meaningful (equivalent bet shapes, temporal alignment). It warns that most pre-mapped topics return compatibility warnings. However, it does not explicitly compare to sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by stating scoping to an identifier and the ability to list all keys when omitting the argument. 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?

Three sentences, front-loaded with the main function, followed by usage examples and scope. Every sentence is necessary and concise.

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

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

Given one optional parameter and no output schema, the description completely covers retrieval, listing, scope, and pairing with related tools. 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?

Only one parameter (key) with 100% schema coverage. The schema description already mentions omitting to list all keys, so the tool description adds no additional meaning beyond the schema.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, with a specific verb ('Retrieve') and resource ('a value previously saved via remember'). It distinguishes from siblings 'remember' and 'forget'.

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

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

The description explains when to use ('look up context the agent stored earlier') and implies not to use for new computations. It pairs with remember/forget but does not explicitly state when to avoid using this tool.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds behavioral detail: 'Set mark_read:true to flag returned events read so the next call only shows newer ones', and mentions the feed is identical to a REST endpoint. No contradiction with annotations.

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

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

Four sentences front-loaded with purpose, each sentence adds unique value (returns fields, filtering, mark_read behavior, alternative access). No unnecessary words.

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

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

No output schema, but description explains return fields ('source, citation_uri, raw event payload'). Covers filtering parameters, mark_read effect, polling suitability, and alternative access method. Complete for a list-retrieval tool.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by explaining the effect of mark_read ('so the next call only shows newer ones') and providing an example for type filter ('e.g. "sec_8k"'). This goes beyond the schema's descriptions.

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

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

The description clearly states 'Pull fired events from your subscription feed' with specific verb 'Pull' and resource 'fired events/alerts'. It distinguishes from sibling tools like list_subscriptions which list subscriptions rather than events.

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 mentions 'Polls work fine' and provides alternative access via a direct REST endpoint, giving context on when to use this interactive tool versus scripts/dashboards. No explicit exclusion of other siblings, but sufficient guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds considerable contextual behavior: fans out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), specifies fallback logic, and mentions soft-fail for USPTO. 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 dense paragraph but well-organized, covering purpose, scope, parameters, and fallback behavior. It is efficient and informative, though slightly verbose with the long list of example queries. Still, no wasted sentences.

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

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

Despite no output schema, the description explains the return structure (changes[] grouped by source, total_changes count, pipeworx:// URIs). It covers all important behavioral aspects: multi-source fan-out, fallback, date formats, and when to use the sibling tool. Complete for a tool of this complexity.

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

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

Schema has 100% description coverage (baseline 3). The description adds value by elaborating on the `since` parameter with examples (ISO date, relative shorthand like "30d") and clarifying that `value` can be ticker or zero-padded CIK. This goes beyond schema descriptions.

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

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

The description explicitly states the tool is a change feed for a company, providing multiple usage examples ("latest on Y", "what happened to Z") and clearly distinguishes from sibling tool entity_profile by specifying when to use that instead.

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 examples and explicitly says when to use entity_profile instead. It also details fallback behavior (GDELT→GNews) and soft-fail for USPTO, giving clear guidance on 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 indicate idempotent and non-destructive behavior. The description adds context beyond annotations: persistence details (24 hours for anonymous, persistent for authenticated), scoping by identifier, and pairing with other tools.

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?

Every sentence is informative and earns its place. The description is front-loaded with purpose, explains usage, then adds persistence details and pairing, without any fluff.

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

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

Despite no output schema, the description fully covers the tool's purpose, usage, parameter semantics, storage behavior, and relationship with sibling tools. Complete for a simple store/retrieve tool.

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

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

Schema has 100% coverage with parameter descriptions. The description adds value by providing concrete examples of key naming conventions (e.g., 'subject_property', 'target_ticker') and clarifying the purpose of the value field.

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 verb ('Save'), resource ('data'), and scope ('key-value pair scoped by your identifier'). It distinguishes from sibling tools 'recall' and 'forget' by mentioning them as pairs.

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 ('when you discover something worth carrying forward') and pairs with recall/forget. However, it does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' It also specifies return structures (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand for drug) and notes auto-disambiguation.

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 4-5 sentences, front-loaded with examples. Every sentence adds essential information: what it does, when to use, supported types, input formats, internal behavior, and return values. No wasted words.

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

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

Despite no output schema, the description explicitly details return fields for both entity types (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation URI for drug). It also covers internal cascading behavior. For a lookup tool with two parameters and no output schema, this is fully 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%, so baseline is 3. The description adds meaning beyond schema: it explains that 'value' can be ticker, CIK, or company name for company; brand or generic name for drug. It also provides examples and notes auto-disambiguation, enhancing the schema's enum and description.

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

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

The description clearly states the tool's verb ('resolve'), resource ('NAME to canonical/official identifier'), and scope (supported types: company, drug). It distinguishes from sibling tools by emphasizing it's for name-to-ID conversion, which is unique among siblings like entity_profile or compare_entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It provides concrete examples and lists supported types with input formats. While it doesn't explicitly state when not to use or list alternatives, the guidance is clear for a foundational lookup tool.

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

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

Annotations already indicate readOnly=true and idempotent=true, and the description aligns with these by describing a FETCH operation. It adds valuable context: pagination with offset/limit, per-field filtering, field projection, sorting, and API page size caps. 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 concise yet comprehensive. It opens with the primary purpose, then enumerates capabilities, provides a concrete example, and ends with a usage hint about 'resource_meta'. Every sentence adds value; no filler.

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

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

The tool has no output schema, but the description partially compensates by listing example fields (state, district, commodity, etc.) from the example resourceId. However, it does not state the return format (e.g., array of objects). Given the tool is read-only and well-parameterized, this 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?

With 100% schema coverage, baseline is 3. However, the description adds significant meaning: it explains the resourceId UUID format with a concrete example ('9ef84268-d588-465a-a308-a864a43d0070') and lists fields from that example, clarifies sort spec mapping, and emphasizes that filter field ids come from resource_meta. This goes well beyond the schema descriptions.

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

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

The description clearly states the action ('Fetch records'), the resource ('any India Open Government Data...resource by its resourceId'), and explicitly distinguishes from the sibling tool 'resource_meta' by advising to use it first to obtain field ids. It also lists supported operations (pagination, filtering, projection, sorting), leaving no ambiguity.

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

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

The description provides explicit guidance on when to use this tool (when resourceId is known) and directs users to the sibling tool 'resource_meta' for field discovery. It does not explicitly state when not to use it, but the context is clear and sufficient for an agent to decide.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value by detailing the specific return fields (title, org, sector, last-updated, fields with name/id/type) and the usage context. This additional behavioral context justifies a score above baseline.

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

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

The description is three concise sentences. The first sentence states purpose and return fields. The second provides actionable usage guidance. The third explains the resourceId origin. No waste, front-loaded with purpose.

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

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

For a simple metadata-fetching tool with no output schema, the description is complete. It explains what is returned, how to get the resourceId, and when to use it relative to a sibling. Annotations cover safety. No gaps identified.

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

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

Schema description coverage is 100%, with both parameters well-described. The description does not add new parameter-level semantics beyond what the schema provides (e.g., resourceId format and purpose are already in 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 the tool fetches schema/metadata for a data.gov.in resource by resourceId, listing specific metadata fields (title, org, sector, last-updated, fields). It distinguishes itself from the sibling resource_data by noting its use to discover field IDs before calling resource_data.

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

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

Explicitly tells when to use this tool: 'Use this to discover the filterable/sortable field ids before calling resource_data.' This gives a clear workflow context and a prerequisite for the sibling tool. No explicity when-not, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it calls 'ai_visibility_check' per entity, ranks by score, and returns score, confidence, signal density. 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?

Three sentences, front-loaded with key action, no redundancy. Every sentence adds value.

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

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

Covers usage, parameter roles, output format (ranked list with metrics). No output schema, so description suffices. Could mention entity count limit (2-8) but schema already does.

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

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

Schema coverage is 100%. Description adds context: entities array first entry is 'subject', rest competitors; explains 'workers-ai' as free default and 'anthropic' requiring _apiKey; clarifies 'context' for disambiguation.

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

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

The description uses a specific verb ('Compare'), identifies the resource ('AI visibility'), and distinguishes from the sibling tool 'ai_visibility_check' which does single entity checks. It clearly states the action: probing multiple entities and ranking results.

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

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

Provides explicit use case ('competitive AI-marketing audits') and an illustrative question. Implicitly distinguishes from single-entity tool, but lacks explicit when-not-to-use or alternative references.

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. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia first measurement may take 5-30 seconds, sources_failed will list timeouts, and the rest still returns. 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 somewhat lengthy but well-organized. It front-loads the main purpose, then details behavior and return structure. Every sentence serves a purpose, though slightly verbose.

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

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

Given the complexity (multiple sources, partial failures, multiple return fields) and no output schema, the description is exceptionally complete. It explains the summary block, per-advisory detail, links, and alternative versions, making the tool fully understandable.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds minor context (scoped packages accepted, version defaults to latest) but does not significantly extend beyond what the schema provides.

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

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

The description clearly states it is a composite check for deciding whether to add an npm package, covering license, advisories, version history, and bundle info. It uses specific verbs ('scan', 'check') and distinguishes itself from siblings by its 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?

Explicitly tells when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also specifies scope (NPM only in v1) and points to alternatives for other ecosystems (deps.dev:version).

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

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

Annotations already declare readOnlyHint, idempotentHint, etc., but the description adds substantial behavioral details: embedding model (BGE-base-en), windowing (500-char overlapping windows), character cap (200K chars) with truncation flag, and output features (offsets for verification). This goes well beyond annotations.

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

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

The description is well-structured and front-loaded with the main action. It contains multiple informative details but every sentence serves a purpose. A slight reduction in length could improve conciseness, but it remains efficient.

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

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

Despite lacking an output schema, the description explains the return format (top-N passages with character offsets and similarity scores). It covers truncation behavior and pairing with a sibling tool. For a tool with 3 parameters and moderate complexity, this is thoroughly complete.

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

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

Schema description coverage is 100%, providing a baseline of 3. The description adds context: 'text' is described as 'document text to search inside' and 'query' as 'natural-language query' with examples. It explains the 200K char cap for 'text' and default for 'limit'. This adds meaning beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific verb 'search' and resource 'record text'. It distinguishes itself from sibling tools by explaining when to use it (when record too big for prompt) and how it complements 'ask_pipeworx_grounded'.

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

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

The description explicitly states when to use the tool ('record is too big to cram into the prompt') and mentions a sibling tool for a different workflow ('Pairs with ask_pipeworx_grounded'). It could be more precise about when not to use, but the guidance is clear and actionable.

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

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

The description goes beyond annotations by detailing that the tool requires an authenticated account, imposes SMS limits, provides webhook signing secrets once, and auto-disables webhooks after failures. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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 bullet points and front-loaded with the main purpose. It is slightly verbose but every sentence adds value; concise enough given the complexity.

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

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

The description covers all aspects: purpose, requirements, supported types with examples, delivery channels with constraints, and behavioral notes. Without an output schema, it adequately explains return values (subscription ID and webhook secret once).

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?

Despite 100% schema coverage, the description adds significant value by providing concrete examples for each subscription type and delivery channel, explaining the params object structure, and clarifying constraints like phone verification and SMS caps.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes from siblings like unsubscribe and list_subscriptions by focusing on the creation aspect.

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

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

The description specifies when to use the tool (creating a subscription) and notes prerequisites like a Pipeworx OAuth account and verified phone for SMS. However, it does not explicitly mention when not to use it or alternatives for different subscription needs.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds value by revealing that results are drawn from a 'live catalog of thousands of tools' and that each returned question includes 'the exact tool + argument shape'. 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 relatively long but well-structured: it starts with common questions, states the purpose, explains the return value, and gives usage instructions. Front-loading key phrases helps agents quickly grasp the tool's role. A minor reduction in length would improve conciseness.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all necessary aspects: purpose, when to use, what it returns, and how to use the parameter. It fully explains the tool's role in an onboarding flow, making it complete for its complexity level.

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

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

With 100% schema coverage, baseline is 3. The description adds meaning by explaining the effect of omitting vs. providing the 'topic' parameter ('pass topic... to focus'), and lists example values that align with the schema's description. This goes beyond just restating 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: an onboarding entry point that returns example questions categorized by topic. It uses specific verbs ('Returns category-bucketed example questions') and distinguishes itself from sibling tools like ask_pipeworx and discover_tools by noting it provides tool+argument shapes from the live catalog.

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 to use this tool first when unsure of Pipeworx's capabilities, and explains when to omit or pass the 'topic' parameter ('Omit for a cross-category spread'). While it lacks explicit exclusions (e.g., 'do not use if you already know what to ask'), the context is clear enough for effective agent decision-making.

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: ownership enforcement and deactivation semantics. Annotations already indicate non-destructive write, but the description details the exact side effect and references to recent_alerts. 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?

Two sentences, front-loaded with the action, no extraneous words. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, and side effects. Could mention error handling for non-existent id or unauthorized use, but not critical.

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 does not add new details about the parameter beyond what is in 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 action ('Cancel a subscription by id') and the resource (subscription). It distinguishes itself from siblings like subscribe (creates) and list_subscriptions (lists).

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 important usage context: ownership enforcement (you can only cancel your own subscriptions) and the deactivation behavior (not deleted, history via recent_alerts). However, it does not explicitly state when not to use this tool or name alternative tools for similar tasks.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that the tool returns a verdict, extracted structured form, actual value with pipeworx:// citation, and percent delta, and that it replaces 4-6 sequential calls. 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 front-loaded with usage examples and key purpose, then provides details on scope and output. It is fairly long but each sentence adds value. Could be slightly more compact, but well-structured.

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

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

For a simple tool with one parameter and no output schema, the description fully covers what the tool does, its domain, input format, and output structure. It is complete and self-contained.

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

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

The single parameter 'claim' has a detailed schema description (100% coverage). The description adds value by providing example claim strings like 'Apple's FY2024 revenue was $400 billion' and explaining the natural-language nature.

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 does natural-language claim verification against authoritative sources for company-financial claims, with specific examples like 'Apple's FY2024 revenue was $400 billion'. It distinguishes itself from sibling tools by focusing on fact-checking rather than entity resolution, search, or other operations.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the domain (company-financial claims). It does not provide explicit when-not-to-use guidance, but the context is clear enough.

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