Sbir

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) indicate safe, read-only behavior. The description adds that the default model is free, Anthropic requires a BYO key with direct payment to Anthropic, and discloses the return shape (per-model score, confidence, signals, raw_response). 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 five sentences, front-loaded with the core action, and each sentence provides necessary detail without redundancy. No fluff.

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

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

Given no output schema, the description adequately describes the return structure. With 4 parameters (1 required), 100% schema coverage, and no enums or nested objects, the description covers all needed information: what it does, parameters, return shape, and use cases.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description adds value by clarifying the default model for 'models', the purpose of '_apiKey' (passed through to Anthropic), and how 'context' helps disambiguate. This is helpful but not critical.

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 probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the default model, optional Anthropic probing, and the return structure. This distinguishes it from siblings like scan_competitor_ai_presence.

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

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

The description lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the Anthropic model (requires _apiKey). It does not explicitly state when not to use this tool or name alternatives, but the provided context 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?

The description adds valuable context beyond annotations: it explains that the tool routes to verified sources, fills arguments automatically, and returns structured answers with pipeworx:// citation URIs. This complements the readOnly and idempotent hints.

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

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

The description is front-loaded with the key directive ('PREFER OVER WEB SEARCH'), is efficiently written without wasted words, and every sentence contributes meaningful information.

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

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

Given the tool's complexity (routing to thousands of sources) and no output schema, the description sufficiently explains what the tool does, when to use it, and what to expect (structured answer with citations). It is complete for an agent.

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

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

Schema coverage is 100% with alias descriptions. The description enhances the parameter by specifying the kind of natural language questions accepted and provides examples, adding practical guidance beyond the schema.

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

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

The description clearly states the tool's purpose: routing factual questions to authoritative structured data sources, with specific examples of domains (SEC, FDA, etc.) and a directive to prefer over web search. It distinguishes itself from general web search and is unambiguous.

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

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

Explicitly states 'PREFER OVER WEB SEARCH' and provides a comprehensive list of when to use: for factual questions about real-world entities, numbers, etc. It includes specific example queries, giving clear usage 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, openWorldHint, idempotentHint, and destructiveHint. The description adds critical behavioral details: it extracts answers using only tool results, returns explicit refusal reasons (not_in_source, etc.), and costs an extra LLM call. 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 each sentence adds value. It is well-structured: purpose, mechanism, return format, usage guidance. It could be slightly more concise, but it remains clear and informative.

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

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

Despite lacking an output schema, the description compensates by detailing the return format (answer, evidence, confidence, etc.) and possible refusal reasons. It explains the complex routing across 3,775 tools. This makes it sufficiently complete for an agent to understand behavior 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 description coverage is 100%, so baseline is 3. The description mentions aliases like q, prompt, but these are already in the schema. It does not add substantial 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 explicitly states the tool provides 'Hallucination-resistant answer mode for high-stakes reads,' details its routing and extraction mechanism, and distinguishes itself from sibling 'ask_pipeworx' by mentioning the extra extraction step and explicit refusal behavior. It lists return fields and refusal reasons, making its purpose very clear.

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

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

It provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' and when-not-to-use: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This clearly differentiates from its sibling.

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 readOnly/openWorld/idempotent. The description adds extensive behavioral details: fan-out patterns, response shapes, low-confidence short-circuit, closed-market handling, spread warnings, cancellation rule parsing, and resolver contract inspection. 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?

Front-loaded with core purpose and usage. Structured sections (CLASSIFIERS, FAN-OUT, etc.) aid readability. However, some details are repeated (e.g., resolution risk mentioned twice) and could be tightened.

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

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

Given complexity (many classifiers, fan-outs, no output schema), the description is exceptionally thorough. Covers edge cases, safety mechanisms, cancellation rules, and guides agents to inspect match confidence. Leaves no essential gap.

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

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

Schema has 100% coverage with descriptions. The description adds value by explaining depth enum ('quick=2-3 sources'), include_raw effect on response size, and examples of market input. Provides richer context than schema alone.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies three input types (slug, URL, question) and distinguishes from siblings like polymarket_edges by targeting 'should I bet on X' queries.

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 use cases ('should I bet on X', etc.). Implicitly excludes other tools via sibling context. Lacks explicit 'when not to use' statements but covers when to inspect resolver confidence before acting.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable detail: it pulls latest SEC data, handles off-calendar fiscal years, sorts by primary metric, and returns paired data with citation URIs. No contradictions.

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

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

The description is front-loaded with trigger phrases and examples, but it is slightly verbose. However, every sentence adds value, so it remains effective.

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

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

Despite no output schema, the description explains return values (paired data, citation URIs) and sorting behavior. It covers both entity types thoroughly, making the tool's behavior fully discernible.

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

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

Schema coverage is 100%, but the description adds meaning by explaining enum values with examples (e.g., 'AAPL','MSFT' for company) and detailing the data fetched per type, enhancing understanding beyond the schema.

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

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

The description uses specific verbs like 'compare', 'rank', 'head to head' and clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes from sequential lookups, making the purpose unmistakable.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It specifies when to use company vs drug types and what data each pulls, providing clear context and alternatives.

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

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

Adds significant context beyond annotations: time expectation (15-60s), platform requirements, guarantee of no invented facts, and return of gaps[]. Annotations already declare readOnly, openWorld, idempotent.

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

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

Front-loaded with core value; dense but not overly long. Some marketing language (e.g., 'facts arrive pre-verified') and URL add minor clutter but still effective.

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

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

Very complete for a complex tool: covers input, output (structured findings with citations, confidence, gaps), behavioral guarantees, and prerequisites. No output schema, but description compensates fully.

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 reinforces meaning: question should be broad, depth enum values explained with defaults. Adds context about paid plan for thorough. Slightly redundant with schema but adds value.

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

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

Clearly states it performs grounded multi-source research in one call, decomposing questions into sub-questions and routing to many tools/sources. Distinct from sibling ask_pipeworx which is for single 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 recommends use for broad or multi-part questions and directs to ask_pipeworx for single lookups. Also notes account requirements and paid plan needed for 'thorough' depth.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context about returning 'the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' This adds value beyond annotations but does not disclose additional traits like rate limits or pagination.

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 core mission ('Find tools by describing the data or task') but then lists many example domains, making it somewhat long. While informative, it could be more concise. The structure is a single paragraph with no bullet points or clear separation.

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

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

Given the tool's purpose (search/discovery) and the presence of full schema coverage, the description adequately explains what the tool returns and how it behaves. It mentions the default/limit of results (20, max 50) and that schemas include curated examples. However, it does not clarify behavior for empty results or error cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds aliases information ('Accepts task, q, description, search as aliases') and provides example queries, which adds some value beyond the schema descriptions. However, the schema already describes each parameter adequately.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous concrete use cases (SEC filings, FDA drugs, etc.) and specifies the return value (top-N tools with schemas). The description also distinguishes this discovery tool from sibling tools by advising to call it FIRST when exploring options.

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 when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use the tool, though it does not explicitly list alternative tools for specific 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 mark it as read-only, open-world, idempotent, and non-destructive. The description adds behavioral details: fans out across multiple sources, returns specific fields, and mentions that USPTO PatentsView API sunset May 2025 with soft-fail behavior. No contradiction with annotations.

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

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

The description is a single dense paragraph but is front-loaded with example queries and contains no redundant sentences. Slightly more structure (e.g., bullet points) could improve readability, but it is concise and effective.

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

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

Despite no output schema, the description enumerates returned fields (cik, company_name, recent_filings with URIs, fundamentals, patents with sunset note, news, LEI). It covers edge cases (patent soft-fail, name unsupported) and is complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds crucial context: 'value' must be ticker or zero-padded CIK, names are not supported, and directs to resolve_entity for name resolution. This meaningfully extends 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 opens with diverse example queries ('Tell me about X', 'research Acme', etc.) and clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from siblings like resolve_entity by noting that names are not supported.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use (names) and directs to resolve_entity as alternative.

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

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

Annotations already indicate destructive (destructiveHint=true) and non-read-only (readOnlyHint=false). The description adds valuable context about the types of data (memories) and use cases (stale, done, sensitive). However, it does not describe any side effects like cascading deletions or confirmation behavior.

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

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

Two sentences: first succinctly states the action and resource, second provides usage guidance. No unnecessary words or repetition. Front-loaded with the core 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?

Given the tool's simplicity (1 parameter, no output schema), the description covers purpose, usage, and sibling relationships. It lacks mention of return behavior (e.g., success/failure indication), but this is minor for a simple deletion tool with annotations present.

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 defines the 'key' parameter. The description confirms its role but adds no new detail beyond 'Memory key to delete' from 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?

Explicitly states 'Delete a previously stored memory by key', clearly identifying the action, resource, and parameter. Distinguishes from siblings 'remember' and 'recall' by being the inverse operation.

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

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

Provides explicit guidance on when to use: stale context, task completion, clearing sensitive data. Also mentions pairing with 'remember' and 'recall', giving clear context relative to alternatives.

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

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

With annotations indicating readOnlyHint, idempotentHint, and non-destructive, the description adds behavioral context by detailing the process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format') and output format ('single text blob ready to drop at site-root/llms.txt'). This goes beyond the annotations.

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

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

The description is two sentences long, front-loaded with the core purpose, followed by process and use cases. Every sentence adds value without redundancy or fluff.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description covers input (URL), output (text blob), and process. It is complete for its complexity, though it could mention error handling or limitations if URL is invalid.

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 clear parameter descriptions for 'url' and 'max_links'. The description does not add additional meaning beyond what the schema already provides (e.g., defaults and max for max_links are in the schema). With high coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt file', and the purpose of helping AI crawlers index sites. It distinguishes from sibling tools which are unrelated (e.g., sbir_search_awards).

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 by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use it, though it does not mention when not to use or 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 readOnly, idempotent, and non-destructive behavior. The description adds behavioral context about default filtering (active only) and return details, complementing the annotations well.

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

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

Two sentences: first states purpose and return fields, second provides usage guidance. Minimal, efficient, and front-loaded. No wasted words.

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

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

For a simple tool with one optional parameter, the description covers purpose, return structure, and usage guidance. Annotations provide safety context. 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?

The only parameter (include_inactive) is fully documented in the input schema with 100% coverage. The description does not add additional semantics, but none are needed.

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 lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). It distinguishes itself from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear guidance on when to use the tool, though it could mention when not to use it.

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

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

Beyond annotations, the description discloses it is rate-limited to 5 per identifier per day, free (no quota usage), and notes that feedback directly affects the roadmap. This adds valuable behavioral context.

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

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

The description is concise and well-structured. It front-loads the main purpose, then provides usage guidelines and constraints in a clear, sequential manner. No unnecessary words.

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

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

Given the tool has no output schema and moderate complexity, the description covers all necessary aspects: when to use, what to include, rate limits, quota, and even what not to do. It is fully complete for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds practical guidance: explains the 'type' enum values, advises on how to write the 'message' (specific, 1-2 sentences, 2000 chars max), and clarifies the optional 'context' object. It enhances the 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's purpose: sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes itself from sibling tools by being specifically for feedback, not for queries or actions.

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 scenarios (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). It also includes practical constraints like rate limits and quota information.

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 valuable context: self-aggregating, no PII, cached 5min-1h. No contradictions with annotations.

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

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

Four sentences, each earning its place: first states output, then lists use cases. No fluff, well-structured, 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?

Despite no output schema, description specifies return fields (top tools, top packs, total call volume). Covers data source, caching, privacy, and window behavior. Complete for a simple tool with one parameter.

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, including enum values and descriptions. Description adds explanatory context for the window parameter ('shorter windows surface what's hot right now; longer windows show steady-state demand'), enhancing understanding beyond schema.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over recent windows. It provides three specific use cases (discovering hot data sources, confirming canonical choices, aligning use cases). The tool's purpose is distinct from siblings like discover_tools or ask_pipeworx.

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

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

Explicitly describes when to use it with three scenarios. Lacks explicit when-not-to-use or alternative tool names, but the given use cases provide clear context for appropriate usage.

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

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

The description extensively discloses behavioral traits beyond annotations: internal logic (monotonicity violations, partition checks, fill check with book depth), constraints (Jaccard similarity threshold, partition filter), and failure conditions (placeholder slugs, thin legs). 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 well-structured with clear sections and front-loads the core requirement. However, it is somewhat lengthy with extensive technical detail that could be condensed. Still, it remains readable and organized.

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

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

Given the complexity and lack of output schema, the description is remarkably complete. It explains the output format, internal checks (fill_check, partition_check), edge cases (placeholder slugs, realizable edge), and directs to polymarket_fill_risk for further needs. No gaps apparent.

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?

Although schema descriptions cover 100% of parameters, the description adds substantial extra semantics: how each parameter is used in detail (single-event walks child markets, topic searches related events), internal processing (partition_check, fill_check), and edge cases (semantic anchor, partition filter). This goes far beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between single-event and cross-event modes and mentions related tools like polymarket_fill_risk for custom sizing, providing clear differentiation from siblings.

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

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

The description explicitly states that one of 'event' or 'topic' is required and that calling with no args fails. It explains when to use each mode: event for a specific market, topic for cross-event scanning. It also advises using polymarket_fill_risk for custom sizing, providing clear alternatives.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral details beyond annotations, such as caching (KV 1h), edge computation methods, filter diagnostics, and per-model-family explanations. 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 very long and dense, packing extensive technical detail. While well-structured with segments, it could be more concise. Some redundancy exists (e.g., repeating default values from schema). Front-loading is effective but overall verbosity may hinder quick agent parsing.

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 the response structure (by_segment, fed_candidates, _diagnostics), model families, and all parameter effects. It covers caching, filter knobs, and diagnostic output, making it fully self-contained for agent decision-making.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing rationale for each parameter (e.g., 'Skips opportunities that are too small to bet sensibly' for min_kelly, 'Polymarket has zero trading fees...' for slippage_pp). This goes beyond the schema descriptions.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan/return), resource (Polymarket markets), and unique purpose (discrepancy detection), distinguishing it from sibling tools like polymarket_arbitrage.

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

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

The description indicates the tool is 'Built for "what should I bet on today"' and explains three segments, but lacks explicit guidance on when not to use it or how it compares to siblings. No exclusions or alternative tools are 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds rich behavioral context: it explains the response structure (tracked, expired, snapshot_dates), how snapshots work, computation of trend and decay, and limitations like TTL and decay basis. 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 efficiently packs valuable information: it front-loads the key question, then details the response structure and limitations. Every sentence adds value, though it could be slightly more concise.

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

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

Given no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]), the meaning of each field, limitations, and parameter effects. It is complete and leaves no ambiguity about what the tool returns or how it behaves.

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

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

The input schema has 100% coverage with descriptions for both parameters. The description restates them and adds additional meaning: for 'days', it clarifies the default and clamp range; for 'window', it explains the snapshot family concept. It also ties parameters to the response structure, adding 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's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question and distinguishes this tool from sibling tools like polymarket_edges, which likely provides only current 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?

The description provides clear context on when to use this tool: to understand edge persistence and decay over time, contrasting fresh vs old edges. It lacks an explicit 'when not to use' statement or direct naming of alternatives, but the context is sufficient for an 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, making the tool's safety profile clear. The description goes beyond by detailing the internal behavior: walking the ladder, computing VWAP fill price, slippage, and per-leg fill details. It also warns about the dominant loss mode (unhedged directional position from partial fills). This adds significant context beyond annotations.

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

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

The description is well-structured with clear mode separation (SINGLE-MARKET vs BASKET), bolded warnings, and a focused summary at the end. Every sentence adds essential information without redundancy. It is appropriately lengthy for the complexity but packs no fluff.

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

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

The tool has no output schema, so the description carries the burden of explaining return values. It enumerates all returned fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc., and for basket: theoretical_sum, realizable_sum, capture_ratio, etc.). It also warns about forced_directional_risk and thin_legs. This provides sufficient context for an agent to understand what to expect, though a structured output schema would improve completeness.

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

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

Schema description coverage is 100%, meaning all parameters have descriptions in the input schema. The description adds value by explaining the different interpretations of 'side' and 'size_usd' between single-market and basket modes, including default behaviors and the auto-detect logic for basket side. It also mentions value clamps (10–1,000,000) that may not be in schema. This extra context improves parameter understanding.

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

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

The description opens with a precise verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market vs basket) and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool. The return fields are listed, reinforcing 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 guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the reasoning—theoretical overround on thin books is not capturable and partial basket fills create directional risk—thus telling the agent when and why 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 declare readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral details: two modes, safety fields (compatibility_warning, temporal_alignment, skipped counters), and why spreads may be unreliable. There is no contradiction with annotations.

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

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

The description is well-structured and front-loaded: it states the main purpose, then explains modes, response structure, and safety fields. Every sentence adds value, and it is appropriately detailed for the tool's complexity without being verbose.

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

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

Despite no output schema, the description fully details the response structure (prices, spread, compatibility_warning, temporal_alignment, skipped counters) and calibrates expectations. It covers all necessary behavioral and usage context, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% and each parameter is described clearly. The description adds meaning by explaining the two modes (topic vs explicit tickers), that explicit parameters override topic, and the relationship between parameters. This goes 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 explicitly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts vs explicit tickers) and explains the spread's meaning (Kalshi - Polymarket). This clearly differentiates it from sibling tools like polymarket_arbitrage.

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

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

The description provides clear context on when to use (compare prices across venues) and warns that most pre-mapped topics return compatibility_warning, advising that pre-mapped ≠ tradeable. It explains safety fields that guide usage. However, it does not explicitly state when NOT to use or mention alternatives beyond the tool itself.

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 and idempotent. Description adds important behavioral context: scope per identifier, dual behavior (list vs retrieve), and connection to remember/forget, going beyond annotations without contradiction.

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

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

Three sentences, each with distinct purpose: core functionality, use case examples, scope/pairing. No unnecessary words, information 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?

For a simple read-only tool with one optional parameter, the description covers behavior, purpose, scope, and sibling relationships. No output schema needed; completeness is achieved.

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

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

Schema already describes the key parameter well (100% coverage). Description adds value by providing concrete examples of key usage (ticker, address, notes) and clarifying scope, exceeding baseline.

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

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

The description clearly states the tool retrieves a stored value by key or lists all keys, with specific examples of usage (ticker, address, notes). It distinguishes from siblings like remember and forget by explaining it as the lookup counterpart.

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

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

The description gives clear context for when to use (looking up previously stored context) and explicitly pairs with remember/forget. It lacks explicit 'when not to use' or alternatives, but the use case is well-defined.

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

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

Adds value beyond annotations by explaining mark_read behavior (flags events as read), polling suitability, and return fields. 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 with no wasted words. Front-loads main purpose, then details, then practical notes. Very concise and well-structured.

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

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

Reasonably complete given no output schema and good annotations. Covers parameters, return fields, and alternative access. Missing explicit mention of ordering (assumed most recent recent), but limit suffices.

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?

Adds meaning beyond schema, especially for mark_read (flagging reads) and context on polling. Schema already provides good coverage (100%), so the description supplements effectively.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the resource (alerts) and verb (returns). It differentiates from sibling tools like list_subscriptions by focusing on event retrieval.

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

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

Provides context on when to use (polling works) and an alternative access method (direct API). Does not explicitly state exclusions, but the guidance is clear.

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

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

Annotations declare the tool read-only, idempotent, and non-destructive. The description adds significant behavioral detail: it fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO; explains GDELT preference and GNews fallback conditions; mentions PatentsView API sunset; describes date format behavior (ISO or relative); and specifies the return structure (grouped changes, total count, citation URIs). This goes well beyond the annotations.

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

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

The description is concise yet packed with essential details. It is well-structured: opens with examples, states main function, explains internal behavior (multi-source, fallback), provides parameter guidance, and ends with an alternative tool reference. Every sentence adds value; no redundancy or fluff.

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

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

Given the tool's complexity (multiple data sources, fallback logic, date parsing, return structure) and the absence of an output schema, the description is remarkably complete. It covers the return format (changes[], total_count, citation URIs), fallback behavior, date input formats, and explicitly directs to an alternative tool for different use cases. No gaps remain.

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 extra meaning: it explains the 'since' parameter with both ISO and relative shorthand examples, recommends '30d' or '1m' for typical monitoring, and clarifies 'value' accepts ticker or CIK. This provides operational guidance not present in the schema alone.

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

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

The description starts with a list of example queries that clearly illustrate the tool's purpose ('What's new with X', 'latest on Y', etc.), then states it is a change feed for a company in a time window. It explicitly distinguishes from the sibling tool entity_profile, which is for static profiles. This provides specific verb+resource and 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 provides explicit when-to-use guidance via example queries and a direct alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also clarifies the tool's scope (multi-source, time-window), giving the agent clear context for 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?

Discloses scoping by identifier, persistence details (24-hour anonymous), and non-destructive nature. Annotations confirm idempotent, non-destructive, non-readonly; description adds valuable context beyond annotations.

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

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

Three sentences, front-loaded with action, followed by guidance and technical details. No wasted words.

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

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

For a simple key-value store, the description covers purpose, usage, persistence, and integration with related tools. Output schema is unnecessary.

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

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

Schema covers both parameters with examples. Description adds key-value pair scope and contextualizes usage, enhancing understanding beyond the schema.

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

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

The description clearly states it saves data for later reuse, provides concrete examples (ticker, address, preference), and distinguishes from siblings (recall, forget).

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

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

Explicitly advises when to use ('discover something worth carrying forward'), pairs with recall and forget, and notes persistence differences for authenticated vs. anonymous sessions.

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 context beyond annotations: details internal cascading lookups, output format for each type (ticker, CIK, company_name for company; RxCUI, ingredient, brand for drug), and auto-disambiguation. Complements annotations (readOnly, idempotent) with behavioral depth.

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

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

Front-loaded with purpose and examples; each sentence adds value. Slightly verbose with internal details, but structure is logical and efficient.

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

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

Completely covers input, output, usage context, and internal behavior despite no output schema. No gaps: explains supported types, return format, and that it replaces manual lookups.

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

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

Schema coverage is 100% and already includes detailed parameter descriptions (e.g., examples for value). The tool description adds context but mostly echoes schema info; it does explain output structure per type, providing indirect parameter meaning.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier needed by other tools, with specific examples. It distinguishes itself from siblings like compare_entities by being the first step to obtain IDs.

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

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

Explicitly advises 'Use FIRST whenever you have a name but need an ID', giving clear when-to-use context. No explicit when-not-to-use or alternatives, but it effectively positions itself as the primary name-to-ID resolver.

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 specifying the output is counts for agencies and how to filter. No contradictions with annotations.

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

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

Two sentences: one for purpose, one for usage. Every sentence earns its place; no wasted words. Front-loaded with the 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?

For a simple tool with one optional parameter and an output schema, the description covers the main usage. It mentions 'all major agencies', which might be slightly ambiguous, but overall adequate.

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

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

Schema coverage is 100%, but the description enriches the parameter meaning with concrete examples ('DOD', 'NASA', 'NSF') and explains default behavior when the parameter is omitted.

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

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

The description clearly states the verb 'Get', the resource 'SBIR/STTR award counts', and the grouping 'by agency'. It distinguishes from sibling tools like sbir_company_awards and sbir_search_awards by focusing on aggregate counts per agency.

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: specify an agency for filtered results or omit to see all major agencies. It lacks explicit exclusions or comparisons to alternatives, but the usage context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds what data is returned (amounts, agencies, topics, phases). However, it does not disclose behaviors like pagination, rate limits, or the effect of the limit parameter on completeness.

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

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

The description is a single sentence of 15 words, front-loaded with the key action and resource. Every part adds value, and there is no redundancy or 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 is simple with 2 parameters and an output schema. The description covers return fields but omits important context: the limit parameter may restrict 'complete' history, and no mention of sorting, date ranges, or expected company name format. Adequate but could be more precise.

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

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

Schema coverage is 100% with descriptions for both parameters (company name, limit). The description does not add meaning beyond the schema, e.g., whether company matching is exact or fuzzy. A score of 3 is appropriate given the high schema coverage.

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

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

The description uses a specific verb ('Get'), identifies the resource ('complete SBIR/STTR award history for a company'), and lists returned data (amounts, agencies, topics, phases). This clearly distinguishes it from sibling tools like sbir_get_award (single award) or sbir_search_awards (search by criteria).

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

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

The description implies use when a company's full history is needed, but it does not explicitly state when to prefer this tool over alternatives (e.g., sbir_get_award for a specific award, sbir_search_awards for criteria-based search). No when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by listing specific fields returned (company, award amount, etc.), providing concrete expectations beyond the safety profile. No contradictions with annotations.

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

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

Single sentence front-loaded with purpose, followed by enumeration of key return fields. Every word contributes; no fluff. Ideal conciseness for a simple retrieval tool.

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

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

For a simple get-by-ID tool with output schema present, the description is fully complete. It states what the tool does, identifies the single required parameter, and summarizes what is returned. No gaps given the tool's simplicity and available structured data.

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 (award_id) with schema description 'The unique award ID'. The description mentions 'by ID' but adds no new semantics beyond the schema. With 100% schema coverage, baseline 3 is appropriate; no extra parameter details are needed.

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

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

The description clearly states the verb 'Get' and the resource 'full details for a specific SBIR/STTR award by ID', listing returned fields (company, award amount, agency, abstract, phase, metadata). It distinguishes from sibling tools like sbir_search_awards (search) and sbir_company_awards (by company).

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

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

No explicit guidance on when to use this tool versus alternatives. The purpose is implied (use when you have a specific award ID), but there is no 'when not to use' or mention of sibling tools. Minimal guidance for an agent deciding between options.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the return fields but does not disclose any additional behavioral traits such as pagination limits, sorting, or that results are from the SBIR/STTR database. The burden is partially shared 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 core action and filters, then quickly lists return fields. No unnecessary words or repetition. Ideal 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?

The description adequately covers the tool's purpose and return fields, and the schema handles parameter details. It lacks mention of pagination (default page size, max limit) but that is partially in the schema. The presence of an output schema reduces the need to detail return structure. Slightly incomplete for a search tool that may have pagination behavior.

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

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

Schema description coverage is 100% with each parameter having a clear description. The description lists filterable parameters but adds no extra meaning or constraints beyond the schema, such as format requirements or interdependencies. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Search' and the resource 'SBIR/STTR awards', and lists filterable criteria (keyword, agency, year, company, state) and return fields (company name, award amount, agency, topic, abstract, year, phase). It distinguishes from sibling tools like sbir_get_award (single award) and sbir_agency_stats (statistics).

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

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

The description implies the tool is for searching awards by multiple criteria but does not explicitly state when to use it versus alternatives such as sbir_get_award for a specific award or sbir_company_awards for a company's awards. No when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context about return fields (topic descriptions, agency, dates) and that solicitations are active, which is beyond what annotations provide.

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

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

Two concise sentences: first states purpose, second lists return content. No redundant words. Efficiently structured.

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

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

Given rich annotations and full schema coverage, the description is adequate. Output schema exists and description mentions return fields. Could include default limit or ordering, but not necessary for completeness.

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

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

Schema description coverage is 100%, so baseline is 3. Description mentions 'keyword or agency' but does not add significant meaning beyond the schema's parameter descriptions. No extra semantics for limit or open_only.

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 finds active SBIR/STTR funding opportunities by keyword or agency, and lists return fields (topic descriptions, sponsoring agency, dates). Distinguishes from siblings like sbir_search_awards which search awards.

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?

Implies use for searching solicitations by keyword or agency, but lacks explicit guidance on when to use this vs sibling tools (e.g., sbir_search_awards, sbir_company_awards). No when-not-to-use or alternative suggestions.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds that it internally probes each entity with ai_visibility_check, performs ranking, and returns specific fields (score, confidence, signal density). This goes beyond annotations to explain the orchestration behavior.

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

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

Two sentences plus an inline example. The first sentence states the core purpose, the second explains the internal mechanism and result format. No wasted 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?

The description covers the tool's purpose, input (entities, context), internal process (probes each with ai_visibility_check, ranks), and output (ranked list with score, confidence, signal density). With no output schema, this is sufficient for an agent to understand what it returns.

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 minimal parameter context beyond the schema: it clarifies that the first entity is treated as 'subject' and the rest as competitors, and that context disambiguates. However, it does not elaborate on models or _apiKey beyond what is in the schema.

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

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

The description uses a specific verb 'compare' and resource 'AI visibility across multiple entities', clearly distinguishing it from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison). The narrative of ranking and surfacing most/least recognized makes the purpose precise.

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

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

The description explicitly states the use case: 'competitive AI-marketing audits' with a concrete example. It implies that for single-entity checks one should use ai_visibility_check, but does not explicitly list alternatives. The guidance is clear but could be more direct about when not to use.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond these: it reveals the composite nature (fans out to two sources), the specific return fields, and partial failure behavior including a 5-30s timeout for bundlephobia's first measurement. This is good but not extraordinary given the robust annotation coverage.

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 core purpose and packed with information (sources, usage guidance, return fields, scope, failure modes). Every sentence adds value, though it is somewhat long. Minor reduction for not being maximally 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?

Despite no output schema, the description lists all returned fields (is_latest, license, etc.), mentions per-advisory detail and links, and covers alternative versions. It also describes failure handling. For a composite tool with two external APIs and no output schema, this is very complete. Could be slightly improved by stating the return format explicitly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (package name with scoped packages accepted, version with default to latest). The description does not add significant new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the composite purpose: 'should I add this npm package to my project' check in ONE call, specifying it fans out across deps.dev and bundlephobia. It distinguishes from sibling tools by noting that PyPI/Maven/etc. fall under deps.dev:version directly, implying this tool is for npm only. The verb 'scan' and resource 'dependency' are specific and unambiguous.

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

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

Explicitly states when to use the tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides clear limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives agents clear guidance on appropriate usage versus 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 and idempotent, but description adds substantial behavioral detail: BGE-base-en embeddings, cosine over 500-char windows, 200K char cap with truncation and flag, and character offsets for verification. 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 4-5 sentences, front-loads the core purpose, and each sentence adds unique value: use case, technical details, pairings, constraints. No wasted words.

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

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

Given there is no output schema, the description fully explains what is returned (passages with offsets and scores), handles input constraints (cap, truncation), and provides implementation details. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining the 'text' parameter as the document to search, giving example queries for 'query', and stating the default for 'limit' (5) and range (1-20). This surpasses 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 states 'Semantic search INSIDE a fetched record' and explains the verb-resource: pass text and query, get passages. It distinguishes from siblings by mentioning its pairing with ask_pipeworx_grounded and that it saves context for large records.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides guidance on alternatives ('Pairs with ask_pipeworx_grounded'). This gives clear when-to-use and context for selection.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds important behavioral details: account requirement, type-specific params, delivery channels with rate limits (sms 10/day cap) and webhook auto-disable after 10 failures. 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 information-dense but well-structured: purpose first, then requirements, types, delivery. A bit lengthy but each sentence adds value. Could be slightly more concise, but no waste.

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

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

Given no output schema, the description mentions the return of a subscription id. It covers edge cases like phone verification, rate limits, and webhook auto-disable. Sufficient 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 coverage is 100% and the description enriches all parameters with concrete examples and constraints (e.g., phone must be verified, webhook signing details). Adds significant meaning beyond the raw 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 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, and distinguishes it from sibling tools like list_subscriptions and unsubscribe by focusing on creation. It also mentions the returned subscription id.

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

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

The description specifies requirements ('Requires a Pipeworx OAuth account'), supported event types with examples, and delivery options. It implies when to use (to set up monitoring) but does not explicitly compare to alternatives like list_subscriptions for viewing existing ones. Still, usage context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds behavioral context about the return value (category-bucketed examples with tool+argument shapes) and that it draws from the live catalog. 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 verbose but efficiently packed with useful information. It front-loads common queries and structures content clearly. Minor redundancy could be trimmed, but overall it is well-organized.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It explains usage, return format, use cases, and relationship to other 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?

Schema coverage is 100% with one optional parameter described. The description adds value by providing example values (finance, pharma, etc.) and explaining that omitting the topic gives a cross-category spread, which is not in the schema.

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

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

The description clearly states the tool's purpose as an onboarding entry point that returns category-bucketed example questions from the live tool catalog. It distinguishes from sibling tools by specifically mentioning that it helps users learn what Pipeworx can do and how to call meta-tools.

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

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

The description explicitly says when to use this tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also explains when to pass a topic vs. calling with no arguments, and mentions alternatives like ask_pipeworx and entity_profile.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds value by detailing ownership enforcement, deactivation (not deletion), and that historical events remain available via recent_alerts, providing behavioral context beyond annotations.

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

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

The description is extremely concise with two front-loaded sentences. Every word serves a purpose, and there is no redundancy or 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?

For a simple mutation tool with no output schema, the description adequately covers the outcome (deactivation), persistence of historical data, and ownership constraint. It lacks only a note on return value or confirmation, which is minor.

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

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

Schema coverage is 100% for the single parameter 'id', which is described as 'Subscription id (uuid) returned by subscribe'. The description only repeats 'by id', adding no new semantic information beyond the schema.

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

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

The description clearly states the action 'Cancel a subscription by id' and explains the effect (deactivation, not deletion). It differentiates from deletion but does not explicitly contrast with sibling tools like 'subscribe' or 'list_subscriptions'.

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

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

The description implies usage context by noting ownership enforcement ('only cancel your own subscriptions') and non-destructive deactivation. However, it does not explicitly state when to avoid this tool or provide direct comparisons to alternatives.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds significant context: it returns specific verdict categories (confirmed, approximately_correct, etc.), a structured form, actual value with citation, and percent delta. It also reveals the underlying sources (SEC EDGAR + XBRL) and the multi-step process it replaces. 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 front-loaded with query examples and key purpose, followed by concise explanations of scope, output, and efficiency benefit. Every sentence is informative and there is no redundancy or waste.

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

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

Given the single parameter, no output schema, and thorough annotations, the description fully covers the tool's capability, constraints, and return values. It addresses what claims are supported, what the output contains, and why it's efficient.

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

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

The input schema has 100% description coverage with a well-described 'claim' parameter including examples. The description reinforces the parameter's purpose but does not add new constraints or semantics beyond what the schema already provides.

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

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

The description clearly identifies the tool as a natural-language claim verifier for factual accuracy, with explicit examples of usage queries. It distinguishes itself from siblings by noting it replaces 4–6 sequential calls (NL parsing, entity resolution, data lookup, numeric comparison), implying a composite, specialized function for fact-checking.

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 'Use whenever the agent needs to check whether something a user said is factually correct.' It also limits scope to company-financial claims in v1, providing boundaries. However, it does not explicitly compare with sibling tools like 'ask_pipeworx_grounded' or state when not to use it, which would strengthen guidance.

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