Grants Gov

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: the default model, that Anthropic requires a BYO key with direct payment, and the return structure. No contradictions.

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

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

The description is a single, well-structured paragraph with no wasted words. It front-loads the core purpose and efficiently covers parameters, return format, and use cases.

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

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

Despite no output schema, the description explicitly states the return structure (per-model score, confidence, signals, raw_response + combined view). It covers use cases, default behavior, and key parameters, making it complete for an AI agent to decide when and how to invoke.

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

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

Schema coverage is 100%, baseline 3. The description adds meaningful detail beyond schema: default model name, payment implications for Anthropic, and clarification that context helps disambiguate entities. This exceeds 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 probes LLMs for entity knowledge and returns visibility scores (0-100). It specifies the default model and optional Anthropic integration, distinguishing it from siblings like 'scan_competitor_ai_presence' which may be more targeted.

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 (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not mention when to avoid the tool or compare with siblings. The context gives clear purpose, lacking only explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true. The description adds that it returns structured answers with stable pipeworx:// citation URIs, which is useful context. 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 the key directive and includes examples. It is somewhat long but every sentence provides value, including the list of domains and query examples. Could be slightly trimmed but is well-organized.

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

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

Given the complexity of routing to many tools, the description explains the process and what to expect (structured answer with citation URIs). No output schema exists, but the return format is outlined. Parameter count is high due to aliases, but only one required field. Describes all needed context.

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

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

Schema coverage is 100% with descriptions for all parameters. The description reiterates that the question is in natural language and mentions aliases, but does not add significant meaning beyond the schema. Baseline of 3 is appropriate for high 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 clearly states the tool is for factual questions requiring authoritative structured data, routing to one of 3,745 tools across 884 sources. It uses strong verbs like 'route' and 'returns', and distinguishes from web search by emphasizing structured answers with citations.

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

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

It explicitly says 'PREFER OVER WEB SEARCH' and lists many example domains and query patterns like 'what is', 'look up', 'find', etc. It provides concrete examples. However, it does not compare with sibling tools like search_within or deep_research, only with web search.

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, openWorldHint=true, destructiveHint=false. The description adds critical context: costs one extra LLM call, returns explicit refusal reasons (not_in_source, no_tool_match, etc.), and extracts answer only from tool result, enriching behavioral understanding 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 thorough (multiple sentences) but front-loaded with the most critical purpose and usage info. Each sentence adds value, though it could be slightly more concise without losing clarity.

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 (grounding, refusal reasons, high-stakes use), the description fully covers purpose, behavior, return format (explicit JSON structure), usage guidance, and trade-offs. No output schema exists, but the description compensates by detailing the return fields.

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

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

Schema coverage is 100%, with all 6 parameters documented as aliases for 'question.' The description adds that the parameter accepts natural language but does not provide additional semantic guidance beyond what the schema offers. Meets baseline expectation.

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

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

The description clearly states it's a 'hallucination-resistant answer mode for high-stakes reads,' specifies the action (ask), resource (Pipeworx), and distinguishes from sibling ask_pipeworx by emphasizing groundedness and explicit refusal behaviors.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also advises preferring ask_pipeworx for casual lookups, 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?

The description discloses extensive behavioral traits beyond annotations, including fan-out logic, response shapes, resolver contract, parent event extraction, news field fallbacks, low-confidence handling, spread illiquidity warnings, and cancellation rule parsing. No contradictions with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is long (≈700 words) but front-loaded with a clear purpose sentence. Every section adds value, covering classifiers, fan-out examples, response fields, edge cases, and safety notes. It could be more concise, but for an AI agent the density is beneficial; no tautology or fluff.

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

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

Despite no output schema, the description comprehensively covers response structure (result.market, result.analysis, result.evidence), error states (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), and cancellation rule impacts. All necessary information for correct tool invocation and result interpretation is 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 baseline is 3. The description adds significant value by explaining how parameters affect behavior: `market` accepts slug/URL/question, `depth` controls evidence sources, and `include_raw` impacts response size. This contextualizes usage beyond the schema.

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

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

The description explicitly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly identifies the resource (Polymarket bet) and action (research with data pulling). It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on research and data compilation.

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 contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives input examples (slug, URL, question). However, it does not explicitly exclude use cases or compare with siblings, 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.

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

Discloses data sources, handling of fiscal years, sorting behavior, and return format (paired data + citation URIs). Adds substantial context beyond the readOnlyHint and idempotentHint 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?

Compact paragraph with high information density. Front-loaded with trigger phrases. Each sentence contributes value; no fluff.

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

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

Covers entity types, data sources, sorting, and return format. Lacks explicit enumeration of return fields but adequate given no output schema. Could be slightly more specific about the exact metrics returned for each type.

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

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

Despite 100% schema coverage, the description adds meaning by explaining the difference between company types (ticker/CIK, latest 10-K data) and drug types (names, counts), and gives usage examples.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one call, specifies data sources (SEC EDGAR for companies, FAERS/FDA for drugs), and distinguishes from sequential lookups.

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

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

Explicit trigger phrases given (e.g., 'Compare X and Y', 'which is bigger') and clear preference instruction: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.'

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 details on parallel routing, gap reporting, citations, and account/plan requirements. Does not contradict annotations.

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

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

Description is a single dense paragraph but front-loads the core purpose. Every sentence adds value (usage, behavior, prerequisites, timing). Slightly longer than necessary but 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 2 parameters, no output schema, description covers purpose, usage, behavioral details, prerequisites, timing, and return format (structured findings packet with gaps). No gaps in context.

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

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

Schema coverage is 100%, so baseline 3. Description adds context: enumerates depth options with explicit counts (quick=3, standard=5, thorough=8) and confirms that question can be broad/multi-part. Exceeds baseline by clarifying enum values and usage.

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

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

The description clearly states it performs grounded multi-source research in one call, decomposing questions into sub-questions and routing to multiple tools. It explicitly distinguishes from sibling tool ask_pipeworx 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?

Provides explicit guidance: use for broad or multi-part questions, use ask_pipeworx for single lookups. Also mentions prerequisites (Pipeworx account, paid plan for 'thorough') and expected timing (15-60s).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that results include full input schemas with curated examples ready to call directly, no second lookup needed, which is valuable behavioral context beyond annotations.

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

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

Description is appropriately sized, front-loaded with main purpose, and well-structured. Some redundancy in listing domains could be trimmed, but overall 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 fully explains what the tool returns (names, descriptions, schemas). Given its discovery purpose, it provides all necessary context for an agent to use it effectively.

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

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

Schema coverage is 100% with clear descriptions for all 6 parameters. Description adds examples of natural language queries and mentions aliases, but this largely duplicates schema info. No significant extra meaning beyond schema.

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

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

The description clearly states it finds tools based on task description, lists many example domains, and specifies it returns top-N relevant tools with full schemas. It distinguishes itself from siblings like search_opportunities or deep_research.

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 'Call this FIRST when you have many tools and want to see the option set (not just one answer)', providing clear guidance on when and why to use this tool over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), notes that 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated,' and details the exact data returned. This goes well beyond annotations.

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

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

The description is dense but well-structured. It starts with example queries to quickly convey purpose, then explains the core functionality, and finally lists return fields. Every sentence adds value. While slightly long, the length is justified by the tool's complexity. Minor improvement could be more conciseness in listing examples.

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, no output schema), the description is remarkably complete. It explains what is returned in detail (including field names and sort order for fundamentals), mentions a known limitation (USPTO sunset), and references a sibling tool for name resolution. The description leaves no major gaps for an AI agent to operate correctly.

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

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

Schema coverage is 100%, with both parameters (type and value) fully described in the input schema. The description repeats the schema's points (e.g., ticker or CIK required, names not supported) but does not add new semantic information beyond providing example queries. Baseline 3 is appropriate as the description does not significantly enhance 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 explicitly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific data sources and returned fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and provides example queries like 'Tell me about X' and 'research Acme'. This clearly distinguishes it from siblings like resolve_entity.

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

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

The description includes explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells what inputs to use ('Pass ticker "AAPL" or zero-padded CIK') and what not to use ('names not supported — use resolve_entity first if you only have a name'). This provides clear when-to-use and when-to-avoid instructions.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, and the description's 'Delete' verb aligns. The description adds behavioral context by specifying use cases (clearing stale or sensitive data), but does not discuss idempotency or error handling. Overall, it adds value beyond annotations.

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

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

Three concise sentences: first states action, second provides usage context, third links to siblings. No redundant information; front-loaded with the primary purpose.

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

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

For a simple single-parameter tool with full schema coverage and informative annotations, the description covers purpose, usage rules, and behavioral hints completely. No gaps identified.

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

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

Schema coverage is 100% with one parameter 'key' documented as 'Memory key to delete'. The description does not add further meaning, such as allowed key format or constraints, so it meets the baseline but does not exceed.

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

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

The description clearly states the action ('Delete a previously stored memory by key'), specifying the verb and resource. It distinguishes from siblings by mentioning 'remember' and 'recall', ensuring the agent knows it's the deletion counterpart.

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

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

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall', providing clear guidance on alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds process details (fetches, extracts, emits) and output format ('single text blob'), aligning with 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?

The description is a single, efficient paragraph that front-loads the purpose, explains process, and lists use cases. Every sentence adds value without fluff.

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

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

For a simple tool with two parameters and no output schema, the description covers what the tool does, how it works, and what the output is. It compensates for missing output schema by describing the output 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 coverage is 100%, so baseline is 3. The description adds usage context but does not significantly extend parameter meaning beyond what the schema already provides (e.g., url description is identical).

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 ('generate'), the resource ('llms.txt file for any URL'), and the purpose ('so AI crawlers can index the site cleanly'). It distinguishes itself from siblings by focusing on llms.txt generation, with specific use cases listed.

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

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

The description provides clear usage scenarios ('getting a client's site indexed by AI, drafting for your own project, auditing competitors'). It lacks explicit when-not-to-use or alternatives, but given context, it's adequate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description enhances this by detailing the specific data returned (synopsis, eligibility, etc.), which adds context beyond the annotations. No contradictions.

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

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

The description is a single sentence that efficiently conveys the tool's purpose and the main return fields. Every element earns its place, with no unnecessary words or repetition.

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

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

Given that an output schema exists, the description does not need to detail the return format. It covers the key data categories (synopsis, eligibility, award ceiling/floor, attachments, contact info, version history), which is sufficient for the agent to understand the tool's output. The description is complete for this 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?

The input schema already describes the single parameter (opportunity_id) with full coverage, including its source (returned by search_opportunities as 'id'). The description does not add any additional parameter information beyond what the schema provides, resulting in a baseline score.

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

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

The description clearly states the verb (fetch), resource (Grants.gov opportunity), input (by ID), and lists specific return fields (synopsis, eligibility, award ceiling/floor, attachments, contact info, version history). This distinguishes the tool from siblings like search_opportunities which searches for opportunities.

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

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

The description implies use when you have an opportunity ID and need full details, but it does not explicitly state when to use or not use this tool, nor does it mention alternatives. Given sibling tools like search_opportunities and entity_profile, explicit guidance would improve clarity.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds the fact that it returns active subscriptions by default and can include inactive ones, but does not disclose additional behavioral traits beyond annotations.

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

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

Two concise, well-structured sentences. Front-loaded with purpose and immediately useful information. No fluff.

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

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

For a simple list operation with one optional parameter and no output schema, the description covers purpose, return fields, and usage guidance. No missing critical information.

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

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

The only parameter, include_inactive, is fully described in the input schema. The description does not add extra meaning beyond the schema documentation. With 100% 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 action (list) and resource (subscriptions) and specifies the returned fields: id, type, params, created_at, last_fired_at, fire_count. It distinguishes 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?

Explicitly says to use this tool 'to review what you're monitoring before adding more or to find an id to cancel', providing clear when-to-use context.

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

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

Description discloses key behaviors beyond annotations: rate-limited to 5 per day, free, doesn't count against quota, and team reads digests daily affecting roadmap. No contradiction with annotations (readOnlyHint=false aligns with 'Tell' which is a write).

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

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

Description is concise and well-structured: starts with purpose, then usage conditions, then constraints, and ends with impact. Every sentence adds value; no fluff.

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

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

For a feedback tool with no output schema, the description covers all necessary aspects: when to use, what to include, limitations (rate limit, quota), and how feedback is used. No missing context.

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

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

Input schema already documents all parameters with descriptions and enum values (100% coverage). Description adds specific guidance for the message parameter: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This adds value beyond the schema.

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

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

The description starts with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific use cases (bug, feature/data_gap, praise) and clearly distinguishes from sibling tools by being a feedback submission tool.

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

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

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also provides anti-guidance: 'don't paste the end-user's prompt.' Mentions rate limits and quota.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: self-aggregating signal, no PII, and caching durations (5min-1h depending on window). No contradictions with annotations.

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

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

The description is well-structured with bullet points and concise explanations. It is front-loaded with the core purpose and uses efficient phrasing. Could be slightly more concise, but overall good.

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 optional param, no output schema), the description provides sufficient context: what it returns, use cases, caching behavior, and window semantics. No significant gaps.

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

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

Schema coverage is 100% for the single parameter 'window', which already has an enum and description. The description adds additional semantic value by explaining the trade-off between windows (shorter for hot, longer for steady-state), making it more helpful for agent decision-making.

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

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

The description uses the verb 'Returns' and clearly specifies the resources: 'top tools, top packs, and total call volume over a recent window'. It distinguishes itself from sibling tools by focusing on trending/call volume data rather than entity profiles, searches, or 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 lists three explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case) and explains the window options. While it does not explicitly state when not to use it or name alternatives, the sibling list provides context for differentiation.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are reinforced with behavioral details: monotonicity checks, Jaccard similarity, partition sum, placeholder filtering, and fill check. The description explains internal mechanics and edge cases, adding significant value beyond annotations.

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

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

The description is front-loaded with the key requirement and well-structured, but somewhat lengthy. It includes necessary details like Jaccard threshold and fill check logic, though some sentences could be trimmed without losing value.

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

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

Despite lacking an output schema, the description fully describes the response structure (opportunities[] with fields, partition_check details, fill check behavior). All critical behaviors are documented, making it complete for a complex tool.

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

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

Schema descriptions are 100% covered and already good. The description enriches them with concrete examples (e.g., 'fed-decision-may-2026' for event, 'Fed rate decision' for topic) and clarifies mode distinction, adding extra 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 explicitly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes two modes (event and topic) and explains the core logic. This differentiates it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description warns 'call with no args fails' and provides clear guidance: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It also directs users to polymarket_fill_risk for custom sizing, offering comprehensive usage instructions.

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

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

Annotations already indicate safe read-only, idempotent behavior. The description adds significant behavioral context: caching (1h at KV level), model family details, response structure with diagnostics, and explanations of edge calculations. It thoroughly discloses internal logic without contradicting annotations.

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

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

The description is very long and dense, covering many details. While it is well-structured with clear sections and front-loaded purpose, it could be more concise. Every sentence adds information, but the length may overwhelm agents.

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

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

Given the tool's complexity (9 parameters, no output schema, nested response), the description is thorough. It explains the three segments, diagnostics, caching, and all knob effects, providing a complete picture for correct invocation.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds value by explaining how knobs interact (e.g., 'min_kelly never filters them — this knob applies to the per-leg Kelly') and grouping them as 'Tradeable-edge filters,' enhancing understanding beyond the schema alone.

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

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

The description clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan/return) and resource (Polymarket markets), and distinguishes from siblings by mentioning Pipeworx data vs market price. The phrase 'Built for "what should I bet on today"' further clarifies the intended use case.

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

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

The description provides context such as 'agents discover opportunities without paging hundreds of markets' and details on tradeable-edge knobs, which helps guide when to use the tool. However, it does not explicitly state when to avoid this tool in favor of alternatives like polymarket_arbitrage or search_opportunities, leaving some ambiguity.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. The description adds useful details about history depth (60-day TTL, startup date) and that decay uses daily closes, not intraday. 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 a clear purpose statement, response breakdown, and limits. While verbose, the detail is justified given no output schema. Every section serves a purpose without significant redundancy.

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

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

Given two optional parameters and no output schema, the description covers purpose, parameter effects, response structure (tracked, expired, snapshot_dates), and limits (TTL, startup, data granularity). Missing explicit data types or examples, but sufficient 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?

Input schema covers both parameters with descriptions (100% coverage). The description repeats parameter purpose but adds context linking to response structure (e.g., lookback affects time-series depth). Baseline 3 is appropriate; additional meaning is marginal.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it is shrinking. It distinguishes from sibling tools like polymarket_edges by focusing on historical analysis.

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

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

The description implies usage context (e.g., a 3-week-old wide edge is different from a fresh one) but does not explicitly state when to use this tool versus alternatives like polymarket_edges. No direct comparison with siblings 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds context: walks order book ladder, returns specific fields, and warns about partial fills converting arb to directional position. Minor omission of rate limits or auth, but overall transparent.

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

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

Description is long but well-organized into sections for single-market and basket, with bold key terms. Every sentence adds value, though could be slightly more concise.

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

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

Despite no output schema, description thoroughly explains all return fields. Covers both modes comprehensively including edge cases like thin legs and directional risk.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description adds meaning beyond schema, e.g., explains size_usd differences for buys vs sells and default side determination for basket mode.

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 checks realizable-vs-theoretical edge using live order book depth. It details two modes (single-market and basket) with specific use cases, distinguishing it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly advises 'USE THIS before acting on any polymarket_arbitrage signal or polymarket_edges trade above ~$500'. Also explains when not to use (thin books, partial fills) and warns about the risk of partial baskets.

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 read-only, idempotent, non-destructive. The description adds depth: explains compatibility warnings (shape mismatch, semantic mismatch), temporal alignment field, and skipped cross-type/cross-subtype counters. Discloses that real spreads are rarer than shortcut list suggests.

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

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

Well-structured with clear sections (two modes, response fields, safety fields). Front-loaded with main purpose. Could be slightly more concise but every sentence earns its place. Uses caps for key terms and formatting for readability.

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

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

Given no output schema and high complexity (cross-venue, two modes, safety fields), the description fully explains return format (leg-by-leg prices, spread list, compatibility_warning, temporal_alignment, skipped counters). Leaves no ambiguity about what the tool provides.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds context by explaining the two modes and that explicit parameters override topic. It also lists all 10 topic shortcuts. Baseline 3, plus additional usage context raises to 4.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', specifying the verb (compute spread) and resources (two venues). It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Explicitly describes two modes (`topic` vs explicit tickers) and when to use each. Warns that most pre-mapped topics return compatibility warnings, guiding users away from expecting tradeable spreads. Also explains the compatibility_warning cases, providing clear when-not-to-use criteria.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral details: scoping to user identifier, the ability to list all keys by omitting the argument, and the pairing with remember/forget. This goes beyond annotations without contradicting them.

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

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

Three sentences that are front-loaded with the primary action. Each sentence provides essential information: what it does, when to use it, and how it's scoped and paired. 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?

For a simple retrieval tool with good annotations, the description covers both operational modes (get by key, list keys), scoping, and integration with remember/forget. It lacks explicit mention of return format or error behavior, but these are reasonably inferred.

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. The description adds meaning by explaining that omitting the key lists all keys, and providing concrete examples of keys (e.g., user_research_topic). This enhances understanding beyond the schema description.

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

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

The description clearly states the tool retrieves a valued saved via remember or lists all keys if no key is given. It distinguishes itself from sibling tools remember and forget by naming them and describing the pairing. Use-case examples (ticker, address, notes) provide specific context.

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

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

The description explains when to use the tool: to recall previously stored context without re-deriving it. It suggests pairing with remember and forget but does not explicitly state when not to use it or compare to search tools among siblings.

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

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

The description mentions mark_read:true to flag events as read, which is a state-changing operation, contradicting the readOnlyHint=true annotation. This is a serious inconsistency.

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 clear front-loading of purpose, then details, then extra context (polling, API alternative). No redundant phrasing.

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 covers returned fields (source, citation_uri, payload), all parameters' effects, and usage context (polling, API alternative). Complete for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds valuable context: provides an example for type filter, clarifies since format as ISO timestamp, and explains the effect of mark_read on future calls.

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

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

The description clearly states it pulls fired events from the subscription feed, specifying the verb 'Pull' and resource 'fired events'. It distinguishes itself from sibling tools like list_subscriptions by focusing on alerts/events.

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

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

The description implies usage for retrieving recent alerts and mentions polling works fine, but lacks explicit guidance on when to use this tool versus alternatives like list_subscriptions or the API endpoint.

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

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

Annotations already mark it as read-only, idempotent, non-destructive. The description adds valuable details: fans out to multiple sources, fallback logic (GDELT→GNews on rate limit/5xx), USPTO soft-fail, and return structure including changes[] and pipeworx 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 dense with information but not overly verbose. It front-loads usage examples and then details sources and parameters. 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?

Despite no output schema, the description covers all essential aspects: what it does, sources, limitations, fallback behavior, return structure, and distinction from a sibling tool. It is complete for a complex, multi-source tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds: clarifies 'since' accepts ISO date or relative shorthand, recommends '30d' for monitoring, and explains 'value' can be ticker or CIK. This adds meaning beyond the schema.

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

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

The description clearly states it returns a change feed for a company, with examples like 'What's new with X'. It specifies the exact sources (SEC EDGAR, GDELT→GNews fallback, USPTO) and distinguishes itself from the sibling tool 'entity_profile' for static profiles.

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

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

The description explicitly tells when to use this tool (e.g., 'latest on Y') and when not to ('Use entity_profile instead when you want the static profile'). It also provides context on fallback behavior and parameter recommendations.

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?

Describes scoping by identifier and persistence duration (24 hours for anonymous, persistent for authenticated). Annotations already indicate idempotent and non-destructive, but description adds valuable context on storage 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?

Well-structured with main purpose upfront. Each sentence contributes value, though slightly verbose with multiple examples. Could be tightened, but overall 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?

Fully explains behavior, scoping, persistence, and pairing with related tools. Given no output schema, it adequately covers what the agent needs to know for correct invocation.

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

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

Schema covers both parameters with descriptions. The description adds concrete examples of key formats (e.g., 'subject_property', 'target_ticker') and clarifies that value is any text, 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?

Clearly specifies the verb 'save', the resource 'data', and the context 'across this conversation or across sessions'. Distinguishes itself from sibling tools like recall and forget.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides examples of what to store and mentions pairing with recall and forget for retrieval and deletion.

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, covering safety and idempotency. The description adds context: each call cascades through several lookup endpoints and replaces 2-3 manual lookups. No contradiction with annotations. Extra behavioral detail is useful but not critical.

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

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

The description is dense and well-structured, with front-loaded examples and bullet-like formatting. Every sentence adds value, though some details like 'ticker + 10-digit CIK + company_name' are slightly redundant between the two type descriptions. Still efficient overall.

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?

Without an output schema, the description adequately explains returned values for both entity types, including citation URIs and auto-disambiguation. It covers input formats and internal cascading, but does not address error handling or failure modes. Complete enough for most 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%, but the description adds significant meaning: for company type, it specifies acceptance of ticker, CIK, or name with auto-disambiguation; for drug, brand or generic name. It also details return components (ticker+CIK+company_name, RxCUI+ingredient+brand) and citation URIs, far exceeding schema basics.

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 names to canonical identifiers, with specific examples (ticker, CIK, RxCUI). It distinguishes from siblings by noting 'use FIRST whenever you have a name but need an ID.' The supported types and their outputs are detailed, making 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 says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It enumerates supported types and input formats, but does not explicitly state when NOT to use it or compare to sibling tools like compare_entities. This omission prevents a top score.

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

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

Annotations already indicate safe, idempotent, non-destructive behavior. Description adds rich details: probes each entity, ranks by score, surfaces output structure (score, confidence, signal density per entity), and notes first entity treated as subject. No contradictions.

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

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

Description is front-loaded with purpose, uses 4-5 efficient sentences, no filler. 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?

Despite no output schema, description clarifies return format (ranked list with score, confidence, signal density). Covers all 4 parameters and explains how the tool operates end-to-end, making it 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%, so baseline is 3. Description adds value: explains _apiKey is 'passed to api.anthropic.com per probe', context 'disambiguates common names', and entities 'first entry treated as subject; rest competitors'. Enhances understanding beyond schema.

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

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

Description clearly states 'Compare AI visibility across multiple entities side-by-side', specifies probing with ai_visibility_check, ranking, and surfacing most/least recognized. Distinguishes from sibling ai_visibility_check which handles single entities.

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

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

Explicitly says 'Useful for competitive AI-marketing audits' and gives an example question. Implicitly contrasts with sibling tool ai_visibility_check for single entity checks, but lacks explicit when-not-to-use or alternative names.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds significant detail: fans out across two services, returns structured summary, per-advisory details, links, and alternatives. Explains partial failure behavior (sources_failed lists timeout) and timing (5-30s for new version). 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?

Single paragraph but well-organized: purpose, use cases, return details, scope, failure behavior. Could benefit from bullet points for the return list, but currently clear and without 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?

No output schema, so the description fully compensates by listing return fields, per-advisory details, links, and alternatives. Addresses partial failures, timing, and fallback. Complete for a complex composite tool.

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

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

Schema coverage is 100% with parameter descriptions. The description adds minimal extra meaning: mentions scoped packages and version default, but those are already in the schema. The description's value is in explaining the overall behavior, not in enriching parameter details.

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

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

The description clearly states the tool's purpose as a composite check for adding npm packages, aggregating data from deps.dev and bundlephobia. It explicitly differentiates from sibling tools by specifying NPM-only scope and mentioning fallback for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Provides context on partial failures and timing (bundlephobia first measurement). Lacks explicit 'do not use' conditions but the ecosystem restriction 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 read-only, idempotent, non-destructive behavior. Description adds value by specifying the return fields (opportunity number, title, agency, dates, ALN) and filter options, providing 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 concise sentences front-load the main purpose, then filters, then return fields. No redundant 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?

Given detailed schema and output schema, the description adequately covers purpose, filters, and output fields. Slight gap: mentions 'date range' but no corresponding parameter, which could confuse an agent. Otherwise complete.

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

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

Schema descriptions cover 100% of parameters. Description repeats some filter concepts but adds no new parameter details. Mentions 'date range' for which no parameter exists, causing minor confusion. Baseline score of 3 is appropriate.

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

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

Clearly states the tool searches Grants.gov for federal funding opportunities, specifies that they are 'currently-open or recently-closed', and lists filtering options and return fields. Distinguished from sibling 'get_opportunity' which likely retrieves a single opportunity.

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?

Implicitly indicates usage for searching open/closed funding opportunities on Grants.gov, but lacks explicit guidance on when to use alternatives (e.g., get_opportunity for specific details) or when not to use this tool.

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

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

Description adds details beyond annotations: truncation at 200K chars with flagging, uses BGE-base-en embeddings, 500-char overlapping windows, cosine similarity, returns character offsets for verification. Annotations already declare readOnlyHint, idempotentHint, destructiveHint, 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?

Single dense paragraph, but every sentence adds value. Could benefit from slight structuring (e.g., separate usage and technical details), but it's still concise and 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?

Covers purpose, usage, technical implementation, limitations (200K cap, truncation flag), and integration with sibling tool. No output schema, but description explains return values (top-N passages with offsets and scores). Complete for a semantic search tool.

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

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

Schema has 100% coverage, but description enriches each parameter: text has max chars and truncation, query has examples (e.g., 'supply-chain risk'), limit has default 5. Also adds context about embedding model and windowing.

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 'Semantic search INSIDE a fetched record' and specifies it's for large records that don't fit in the prompt. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides a workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' Gives clear when and how.

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 value beyond annotations by detailing return values (subscription ID), account requirements, type-specific parameters, delivery channel limits (e.g., SMS 10/day cap, webhook auto-disable), and that the webhook signing secret is returned once. No contradictions with annotations.

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

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

The description is concise and front-loaded with purpose. All sentences are substantive. It could be slightly more structured (e.g., bullet points), but it remains efficient and clear.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers essential aspects: types, parameters, delivery options, and account requirement. It lacks error handling or idempotency details, but is sufficient for correct invocation.

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

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

The description elaborates on each parameter with examples and constraints (e.g., sec_8k items codes, delivery channel details), adding significant meaning beyond the schema. Schema coverage is 100%, but the description provides practical guidance.

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

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

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

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

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

The description specifies when to use the tool (to create subscriptions) and includes a prerequisite (requires Pipeworx OAuth account). It does not explicitly state when not to use or list alternatives, but the context is clear given sibling tools.

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

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

Annotations already indicate safe behavior (readOnlyHint, idempotentHint). The description adds that it returns questions with tool+argument shapes, and explains the optional topic parameter. No contradictions.

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

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

The description is detailed but front-loaded with user intents. It packs many concepts into one paragraph, which is effective but slightly verbose. 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 no output schema, the description thoroughly explains what is returned (categorized examples with tool+argument shapes). Parameter usage is clear. Tool's purpose as an onboarding entry point is fully covered.

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% with a description of 'topic'. The description adds that omitting topic gives a cross-category spread, and lists example values like 'finance', 'pharma', etc., enhancing 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 returns category-bucketed example questions with exact tool and argument shapes, positioning it as an onboarding entry point. It distinguishes itself from siblings like ask_pipeworx by specifying its role in learning what Pipeworx can do.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides options (no args or topic) but lacks explicit 'when not to use' alternatives.

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

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

Annotations indicate non-destructive (destructiveHint=false) and idempotent (idempotentHint=true). The description adds context by explaining 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts', which goes 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 with no fluff. Every sentence adds value: purpose, ownership constraint, and behavioral nuance. Front-loads the main action.

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

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

Given low complexity (one parameter, no output schema), the description covers purpose, ownership, and behavioral impact. Could optionally mention return value or success indication, but it's sufficient 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 the parameter 'id' is described in the schema as 'Subscription id (uuid) returned by subscribe'. The description does not add extra meaning beyond what the schema already provides, so 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?

Description clearly states 'Cancel a subscription by id' with the verb 'cancel' matching the tool name 'unsubscribe'. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying the action and ownership constraint.

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 'Ownership is enforced — you can only cancel your own subscriptions', providing clear when-to-use guidance. Does not explicitly mention alternatives, but it's clear that other tools handle different subscription actions.

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

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

Annotations already indicate read-only and idempotent. The description adds that it returns a verdict with citation and delta, and that it replaces multiple sequential calls. This provides transparency about the complexity and efficiency benefits.

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

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

The description is front-loaded with common query patterns, then provides details on domain and output. It is comprehensive but not overly verbose; each sentence adds useful information.

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

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

Despite no output schema, the description fully lists the return fields and explains the tool's scope and efficiency gains. It covers all necessary aspects for an agent to decide usage and understand outcomes.

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. The description adds value by providing examples of valid claims and specifying the domain (company-financial), which aids correct parameter formulation.

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 provides a clear, specific verb 'verify' and resource 'claims' with synonyms. It distinguishes from other tools by explicitly stating its purpose of claim verification against authoritative sources, which is unique among 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?

It states 'Use whenever the agent needs to check factual correctness', giving clear context. However, it does not mention when not to use or explicitly differentiate from alternatives like 'ask_pipeworx_grounded' or 'deep_research', which could also handle factual queries.

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