Samgov

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

Discloses return format per model and combined view, key passing behavior for _apiKey, and default model. Consistent with annotations (readOnlyHint, idempotentHint, etc.). 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?

Concise, front-loaded with purpose, no unnecessary 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?

Despite no output schema, description outlines return structure (score, confidence, signals, raw_response). Sufficient for complex tool with 4 params and clear use case.

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

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

All parameters documented in schema (100% coverage). Description adds extra context: default model, API key usage, and disambiguation help for 'context'. Exceeds baseline 3.

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

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

Clearly states verb 'probe' and resource 'LLMs for visibility scoring', specifying scope (business/brand/product/topic) and output (score 0-100). Distinguishes well from sibling tools like ask_pipeworx or bet_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?

Describes use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and model selection (free default vs. BYO key for Anthropic). Lacks explicit 'when not to use', but context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by explaining how the tool works: it routes questions to the right tool among 3,800, fills arguments, and returns structured answers with pipeworx:// citation URIs. No contradictions with annotations.

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

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

The description is front-loaded with the key guidance to prefer over web search. It is well-structured, with each sentence adding value: it states what it does, gives examples, and explains when to use it. No wasted words.

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

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

Given the complexity of the tool (routing to many tools) and no output schema, the description explains the return format (structured answer with citations). It covers the purpose, usage, and behavior well. Could mention limitations like response time or rate limits, but overall complete.

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

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

Schema coverage is 100% with clear description of the 'question' parameter and aliases. The description adds context by explaining that the parameter accepts natural language and provides examples of valid questions. While the schema already covers the aliases, the description reinforces 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 that the tool answers factual questions using authoritative structured data from 3,800 tools across 904 sources. It distinguishes itself from web search by being 'preferred over web search' for such queries, providing specific examples of data types (SEC filings, FDA data, etc.).

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives clear guidance on when to use: for any factual question about real-world entities, events, or numbers. It lists example question types and provides concrete examples like 'current US unemployment rate' and 'Apple's latest 10-K'.

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 as false. The description adds significant behavioral detail: it describes the refusal mechanism with specific reasons (not_in_source, no_tool_match, etc.), the extraction process using only tool results, and the output structure. While annotations cover safety, the description enriches transparency about failure modes and process. One minor point: the extra LLM call cost is mentioned, but could be more prominent.

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 structured with a clear first sentence defining the tool's nature, followed by behavioral details and usage guidelines. It is front-loaded with key information. However, it is somewhat lengthy (4 sentences) and could potentially be tightened without losing clarity, but it remains appropriately concise for the complexity conveyed.

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 specifies the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and the possible refusal reasons. It also explains the tool's limitations and behavior in failure cases. Given the tool's complexity (routing, extraction, refusal), the description provides complete context for an agent to use it correctly.

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

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

Schema coverage is 100% with all parameters aliases for the question. The description does not add meaningful semantics beyond what the schema already provides (e.g., 'Your question in natural language'). Since coverage is high, baseline 3 is appropriate; the description offers no additional parameter insight.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, and explicitly distinguishes it from the sibling ask_pipeworx by highlighting that it extracts answers only from tool results, refusing when data doesn't directly answer. The specific use cases (e.g., financial verdicts, legal claims) further clarify its purpose.

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

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

The description explicitly states when to use this tool (for high-stakes reads where answers will be quoted, cited, or acted on) and when to prefer the sibling ask_pipeworx (for casual lookups). It also mentions the extra cost (one extra LLM call) as a trade-off, providing clear guidance on alternative selection.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details beyond annotations: resolving markets, classification, fan-out, low-confidence handling, closed markets, wide spreads, resolution-rule risk, parent event extractor, news fallback, and safety mechanisms. 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 very long (over 500 words) but structured with headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence adds information, but some parts could be condensed (e.g., long list of classifiers and fan-out examples). Useful but overly verbose.

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

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

Given the tool's complexity (many classifiers, fan-out, response shapes, safety, resolution risk), the description covers all essential aspects: resolver contract, parent event extractor, news fields, safety, wide spreads, resolution-rule risk. No output schema, but the description explains return structure in detail.

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 meaning: explains depth options, market input formats, and include_raw behavior with examples and context (e.g., fan-out examples). Enriches beyond schema with behavioral implications.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling relevant Pipeworx data in one call. It specifies inputs (slug, URL, question text) and outputs (evidence packet + comparison). It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by emphasizing comprehensive research vs. specific edge/arbitrage.

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

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

The description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples of fan-outs for various bet types. However, it does not explicitly exclude alternatives or compare to siblings, but gives clear usage context.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable detail: for companies it pulls specific financial metrics from SEC EDGAR/XBRL with correct handling of off-calendar fiscal years; for drugs it pulls FAERS counts and FDA data. It also mentions sorting by primary metric and citation URIs. This additional context justifies a 4.

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 example queries and is dense with useful information. Every sentence serves a purpose: specifying triggers, entity types, data sources, sorting, and output format. No wasted words.

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

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

Given the tool's complexity (two entity types, multiple data sources, sorting, citation URIs), the description covers all necessary aspects. It explains return format and unique behaviors like off-calendar fiscal year handling, which are critical for correct usage.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches these by explaining what each entity type returns and the format for values (tickers/CIKs for company, names for drug). This adds meaning beyond the schema's basic enumeration.

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

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

The description uses specific verbs ('compare', 'side-by-side comparison') and clearly identifies the resources (companies or drugs) and the action. It also distinguishes from sibling tools by recommending preference over 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?

Explicitly lists triggers ('Compare X and Y', 'rank these companies') and provides a specific recommendation to prefer this over sequential single-pack lookups. It also quantifies the efficiency gain ('Replaces 8–15 sequential lookups').

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

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

Annotations already indicate read-only and idempotent. Description adds expectations of 15-60s latency, output structure with gaps[], and prerequisites (account and paid plan for thorough). This goes beyond annotations, though some behavioral details like error handling are omitted.

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

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

The description is fairly long but every sentence adds necessary info. It front-loads the main capability and uses examples. Could trim some redundancy but overall efficient.

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

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

Given tool complexity, incomplete output schema, and rich annotations, the description covers all key aspects: purpose, method, output structure, usage context, prerequisites, and timing. It is self-contained and actionable.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds value by explaining depth levels numerically (quick=3, standard=5, thorough=8) and noting paid restriction for thorough.

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

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

The description clearly states the tool performs multi-source research by decomposing questions, routing to 3,800 tools across 904 sources in parallel, and returning grounded findings with evidence. It distinguishes from siblings like ask_pipeworx by explicitly noting when to use each.

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

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

Explicit guidance: 'Use for broad or multi-part questions' and 'use ask_pipeworx for single lookups'. Also mentions account requirement and paid plan for 'thorough' depth.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds behavioral details: returns top-N tools with full schemas ready to call, no second lookup needed. This adds context beyond annotations.

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

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

The description is front-loaded with core function and use case. It lists many domains which is verbose but informative. Each sentence serves a purpose, 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, the description fully explains return value: top-N tools with names, descriptions, and full schemas ready to call. It also covers default and max limit. No gaps for a discovery 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 aliases described. The description adds value by explaining that 'query' is the main parameter, accepts natural language, and lists aliases. Examples are provided, enhancing 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 clearly states the verb 'Find' and the resource 'tools', with specific examples of domains and tasks. It distinguishes itself from siblings by being a discovery tool to browse and search.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies when not to use (if already know the tool).

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

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

Annotations already indicate readOnly, idempotent, openWorld. Description adds behavioral details: fans out across multiple sources, returns specific fields like recent_filings, fundamentals, patents (with sunset note), news fallback, LEI. 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?

Description is somewhat long but efficiently packed with examples, usage guidelines, and return field details. Front-loads with examples and key instructions. Slightly verbose but 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 multi-source complexity and no output schema, description adequately details return fields and behavior. However, it lacks explicit error handling or rate limit info. Still sufficient for an agent to understand inputs and outputs.

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

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

Schema coverage is 100% with descriptions. Description adds context: type is only 'company', value accepts ticker or zero-padded CIK, explicitly states names not supported. This adds useful usage nuance 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 'full cross-source profile of a US public company' with concrete examples like 'tell me about X' and 'company profile for Microsoft'. It distinguishes itself from sibling tools like resolve_entity and deep_research by specifying the holistic nature of the output.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and notes 'names not supported (use resolve_entity first if you only have a name)'. This provides clear when-to-use and when-not-to-use guidance with 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 destructiveHint=true, so the description's 'Delete' is consistent but adds only minor context about use cases. No additional behavioral details 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 sentences, front-loaded with action, every sentence adds value. No extraneous 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?

For a simple deletion tool with one parameter and no output schema, the description covers purpose, usage guidelines, and pairing. Could mention whether deletion is reversible or if confirmation is required, but it's already sufficient.

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

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

The schema has 100% coverage with a description for 'key' ('Memory key to delete'). The description does not add meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states the action ('Delete a previously stored memory by key'), specifies the target resource ('memory'), and implicitly distinguishes from sibling tools like 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with 'remember' and 'recall', providing context 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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false) are aligned and reinforced by description: 'Fetches the page, extracts title/description/key links' confirms non-destructive read behavior. Description adds context about output format and site-root placement.

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

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

Two sentences with a clear lead stating purpose, followed by actions and output, then bullet-like use cases. No fluff, every sentence adds value. Front-loaded with the most essential information.

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

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

With no output schema, the description fully explains the output: 'a single text blob ready to drop at site-root/llms.txt' and mentions it follows 'standard llms.txt markdown format'. Given the tool's simplicity (2 params, no nested objects), this is complete.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description mentions 'url' implicitly ('Fetches the page') and 'max_links' via 'Maximum number of link entries', but does not add new semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a 'production-ready llms.txt file' with specific steps: fetches page, extracts title/description/key links, emits standard format. It distinguishes from siblings by specifying its output (single text blob) and use cases (client site indexing, personal project, competitor auditing).

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

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

Explicitly lists use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This provides clear context on when to use the tool. It lacks explicit when-not-to-use instructions, but the positive guidance is strong.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and idempotentHint. The description adds context by listing return fields and default filtering (active only), which is useful 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 sentences, no wasted words. First sentence states purpose and return fields; second sentence provides usage guidance. Efficient and front-loaded.

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

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

For a simple listing tool with one optional parameter and rich annotations, the description covers key aspects: what it does, what it returns, and when to use it. Could mention idempotency but annotations already cover it.

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

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

Schema coverage is 100% and the schema description clearly explains the parameter. The description does not add additional meaning beyond what is already in the schema, so baseline score is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the return fields. It distinguishes from siblings like subscribe/unsubscribe, though it could be more explicit about scope differentiation.

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

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

Provides explicit usage scenarios: review before adding more subscriptions, or find an id to cancel. Helps the agent decide when to use this tool, but does not reference alternatives explicitly.

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

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

Adds context beyond annotations: team reads digests daily, signal affects roadmap, rate-limited to 5 per identifier per day, free, doesn't count against quota. 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?

5 sentences covering purpose, usage, constraints, and formatting guidelines. Front-loaded and every sentence adds value.

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

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

Covers all necessary context: purpose, when to use, how to format, constraints, and what happens to the feedback. No output schema needed.

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

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

Schema coverage is 100%, so baseline is 3. Description reinforces parameter use cases but doesn't add new semantic details beyond the schema descriptions.

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

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

Clearly states the verb 'Tell' and the resource 'Pipeworx team', and specifies four categories (bug, feature, data_gap, praise). No sibling tool exists for feedback, so it stands out distinctly.

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

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

Explicitly lists when to use each category (bug, feature/data_gap, praise), what not to do (don't paste user prompt), and provides constraints (rate limit, free, no quota impact).

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: self-aggregating signal, no PII, caching duration (5min-1h), and data source (CF analytics-engine), which goes beyond the annotations.

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

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

The description is concise (three sentences plus a bullet list of use cases) and well-structured. Every sentence adds unique value: purpose, use cases, and caching behavior. 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 the tool has one optional parameter with full schema documentation, rich annotations, and no output schema, the description fully covers what it returns (top tools, packs, volume) and behavioral details (caching, no PII). Highly complete for its 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?

With 100% schema description coverage, the baseline is 3. The description adds meaning by explaining the semantic difference between window choices ('hot right now' vs 'steady-state demand'), providing practical guidance beyond the enum values.

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

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

The description clearly states it returns top tools, top packs, and total call volume over recent windows. It distinguishes from sibling tools by focusing specifically on trending data and provides three concrete use cases, making its purpose immediately clear.

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

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

The description explicitly lists three scenarios for use: discovering hot data sources, confirming canonical choice, and aligning use cases. While it doesn't state when not to use it, the context is clear and helpful.

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 behavioral traits beyond annotations: explains the algorithmic checks (monotonicity, partition sum, Jaccard similarity, placeholder filter, fill check with CLOB depth). No contradiction with annotations (readOnlyHint, 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 lengthy but packed with necessary information for a complex tool. It front-loads requirements and uses clear structure (e.g., 'REQUIRES', 'SEMANTIC ANCHOR', 'PARTITION FILTER'). Minor redundancy could be trimmed, but overall efficient.

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

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

Given the complexity, no output schema, and multiple sibling tools, the description is comprehensive. It explains the response fields, tradeability conditions, and differentiates from siblings like polymarket_fill_risk. All key aspects are 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?

While schema coverage is 100%, the description adds significant meaning: explains the difference between event and topic modes, example slugs, semantic anchor, partition filter, and output structure. This goes well beyond the schema's basic descriptions.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific examples, and the verb 'find' clearly indicates the tool's output.

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 each parameter: event for a specific market, topic for cross-event scanning. Mentions that calling with no args fails. Provides guidance on prerequisites (e.g., Jaccard similarity threshold) and when not to trade (fill check).

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. Description adds significant behavioral context: caching strategy (1h KV-level), detailed model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) with formulas, output structure with diagnostics for empty segments, and exclusion rationale for Fed bets. 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?

Description is very long (~400+ words) and covers extensive detail. While well-structured with sections, it is not concise for an AI agent; some repetition or verbosity could be trimmed without losing essential information (e.g., detailed model formulas and diagnostics explanation might be more appropriate in documentation).

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 9 parameters, no required, no output schema, the description thoroughly covers output structure (by_segment, fed sections, diagnostics), all model families with edge and Kelly computation, filter knobs and their effects, and caching behavior. An agent has everything needed to call and interpret results correctly.

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

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

Schema coverage is 100%, but description adds meaningful context beyond schema: explains why min_partition_leg_kelly is needed (min_kelly doesn't filter partitions), defaults and expected values for slippage_pp, and purpose of each knob like max_spread_pp and min_liquidity as tradeable-edge filters.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', specifying verb and resource. It distinguishes from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on edge detection via multiple model families.

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

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

Description explicitly frames the tool as 'what should I bet on today' and explains how it avoids paging hundreds of markets. It provides guidance on tradeable-edge knobs (min_liquidity, max_spread_pp) and notes that Fed bets are excluded. However, it doesn't explicitly contrast with sibling tools like polymarket_arbitrage for when to use each.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: detailed response structure (tracked[], expired[], snapshot_dates[]), computation of trend and decay_pp_per_day, and data gaps (snapshot gaps). 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 front-loaded with a clear analogy and structured explanation of response fields. It is slightly verbose but not excessively so. 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 the tool's complexity (time-series, decay, expired opportunities) and absence of an output schema, the description thoroughly covers response fields, limits, and data gaps. It provides complete guidance for an AI agent.

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

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

Schema coverage is 100% with parameter descriptions. The description adds default values and clamp behavior for 'days' and window family for 'window', but these are minor additions. No significant 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 clearly identifies the tool as providing edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' It distinguishes itself from siblings like polymarket_edges by focusing on historical tracking and decay metrics.

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 differentiate between fresh and old edges) and mentions limitations (60-day TTL, since snapshotting enabled). It does not explicitly state when not to use it or provide alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive hint. The description goes beyond by explaining the internal logic (walks the ladder, checks depth, returns verdicts like 'clean|degraded|cannot_fill') and the risk of forced directional risk in basket mode. 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 verbose but well-structured: it leads with requirements, then details each mode, return fields, and usage advisory. Every sentence adds value, though it could be slightly more concise. The front-loading of 'REQUIRES one of' helps agents quickly understand prerequisites.

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

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

With no output schema, the description fully explains all return values for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp for single; theoretical_sum, capture_ratio, thin_legs for basket). It covers edge cases like forced directional risk and usage thresholds, 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 coverage is 100% with descriptions for all 4 parameters, but the description adds significant value: it explains the dual-mode interpretation of 'side', 'size_usd' as either spend/target proceeds or settlement notional, default behaviors, and clamps. This enriches the schema beyond the 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 it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes, listing return fields for each, and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying its role as a pre-trade validation step.

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 requires one of 'market' or 'event' parameters and advises using this tool 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns about the risk of partial basket fills converting an arb into an unhedged directional position, providing clear context on when and why to use it.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description details response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and explains why spreads may be invalid (non-equivalent bet shapes, temporal gap). It fully discloses the tool's operational behavior.

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

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

The description is lengthy (approx. 300 words) and contains some redundancy (e.g., repeating 'pre-mapped ≠ tradeable'). While well-structured with headings, it could be more concise without losing essential information.

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

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

Despite lacking an output schema, the description fully covers the response format (leg prices, spreads, compatibility fields, temporal alignment, skipped counters) and explains edge cases. It is complete given the tool's complexity.

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

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

Schema coverage is 100%, and the description adds significant meaning: it lists the 10 topic shortcuts, explains how explicit parameters override topic, provides real examples (e.g., 'KXFED-26OCT' for kalshi_event_ticker), and clarifies the relationship between the two modes.

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

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

The description clearly identifies the tool as computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit pairing) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description provides explicit guidance on when to use each mode, notes that most pre-mapped topics currently return compatibility warnings, and warns against assuming pre-mapped topics are tradeable. It explains conditions for interpretation (temporal alignment, bet shape equivalence), effectively telling when the tool's output is meaningful.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds critical scoping context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' This informs the agent of access boundaries. No contradictions.

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

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

Two concise sentences front-load the main action. Every sentence adds value with no fluff. Parameters and scoping are efficiently integrated.

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

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

Despite no output schema, the description explains return behavior: retrieve value or list keys. It covers purpose, usage, scoping, and pairing with siblings. Complete for a simple read 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?

The schema covers the single 'key' parameter 100% with description. The tool description complements by explaining that omitting key lists all keys, adding semantic meaning beyond the schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys when omitted. It specifies the verb 'retrieve' and resource 'value' or 'keys', and distinguishes from siblings (remember, forget).

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

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

The description explains when to use (look up context stored earlier) and pairs with remember and forget. It provides examples (ticker, address, notes) but does not explicitly state when not to use. Still, it gives clear 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?

The description discloses key behaviors: it returns read/unread alerts, allows marking as read, and filters by type and time. This complements the annotations (readOnlyHint, idempotentHint) by explaining the mark_read side effect and the return structure. 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 concise (4 sentences) and front-loaded with the purpose. Each sentence serves a distinct role: purpose, return fields, filtering/marking, and notes on polling/alternative access. No unnecessary words.

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

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

Given no output schema, the description adequately explains what is returned (source, citation_uri, raw event payload). It covers filtering, mark_read behavior, and polling suitability. However, it lacks details on error handling, authentication, or rate limits, though annotations partially fill some gaps.

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

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

The description adds value beyond the schema by providing an example for the 'type' parameter ('e.g. sec_8k') and explaining the effect of 'mark_read' ('flag the returned events read so the next call only shows newer ones'). With 100% schema coverage, baseline is 3, and this extra context raises it 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 the tool pulls fired events from the subscription feed and returns the most recent alerts. It specifies the verb ('Pull', 'Returns') and resource ('fired events', 'alerts'), distinguishing it from siblings like 'list_subscriptions' which list subscriptions rather than alerts.

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 how to filter by type and since, and how to use mark_read to manage read state. It also notes that polling works fine and provides an alternative endpoint for scripts/dashboards, giving context on when to use the tool vs. direct API access. However, it does not explicitly contrast with sibling tools like 'subscribe' or 'list_subscriptions'.

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 the tool is read-only, open-world, idempotent, and non-destructive. The description adds context about multi-source fan-out, fallback logic, relative time shorthand support, and return format (changes[], total_changes, citation URIs), fully disclosing behavior.

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

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

The description is well-structured, front-loaded with example queries, and efficiently conveys functionality. Though dense, every sentence adds value; slight conciseness improvements possible 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 adequately explains return values and behavior for a complex multi-source tool. All key aspects (sources, fallback, parameter formats, return format) are covered, making it complete for the 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?

The schema already covers all parameters (100% coverage), but the description adds value with usage examples (e.g., '30d' for typical monitoring) and explains that 'value' can be a ticker or CIK, going beyond the schema.

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

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

The description clearly states that the tool returns a change feed for a company (SEC filings, news, patents) within a time window. It provides example queries and explicitly distinguishes from sibling tool 'entity_profile'.

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

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

The description gives explicit guidance: use this tool for 'what's new' queries and suggests using 'entity_profile' for static profiles. It also mentions fallback behavior (GDELT→GNews) and soft-failure for patents, aiding decision-making.

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

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

Annotations indicate idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds context beyond annotations: scoping by identifier, persistence duration (24h for anonymous), and pairing with recall/forget. It does not contradict annotations.

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

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

The description is a single dense paragraph that front-loads purpose, then usage, then technical details. Every sentence adds value. It could be slightly improved by structuring into bullet points, but it is concise and efficient.

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

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

For a simple tool with 2 parameters, no output schema, and annotations, the description is fully complete. It explains purpose, usage, technical behavior, and relationships to sibling tools.

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

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

Schema description coverage is 100% with both 'key' and 'value' having descriptive examples. The description adds examples of what to store (e.g., resolved ticker, target address) but does not significantly increase meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('Save'), resource ('data the agent will need to reuse later'), and scope ('across this conversation or across sessions'). It also distinguishes the tool from its siblings 'recall' and 'forget' by explicitly pairing with them.

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

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

The description provides explicit guidance on when to use the tool: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also explains persistence differences based on authentication. It does not explicitly state when not to use, but the context is clear.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses that each call cascades through multiple lookup endpoints internally, effectively combining 2-3 manual steps. It also specifies the exact output fields per type (ticker, CIK, citation URI for companies; RxCUI, ingredient, brand for drugs), giving full transparency on behavior and results.

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

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

The description is well-structured, starting with illustrative queries, then the core purpose, usage guidance, and detailed type breakdown. Every sentence adds necessary context without redundancy. It is slightly lengthy but remains focused and informative, earning a high score.

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

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

Given that the tool has only two parameters, no output schema, and moderate complexity, the description covers all essential aspects: purpose, input format, output details per type, usage context, and internal behavior. Annotations provide safety cues. No gaps remain for effective agent 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?

With 100% schema description coverage, the baseline is 3. The description adds value by providing concrete input examples (e.g., 'AAPL', '0000320193', 'ozempic') and noting auto-disambiguation for company inputs. This clarifies acceptable formats and behavior beyond the schema's general descriptions.

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

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

The purpose is clearly stated with concrete examples ('What's the ticker for…', 'find the CIK for…') followed by a direct statement: 'resolve a user-spoken NAME to the canonical/official identifier'. It also lists supported entity types (company, drug) with details, distinguishing it from sibling tools that perform different lookups or analyses.

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 guidance on when to invoke this tool. It also notes that it replaces 2-3 manual lookups, implying it is the preferred tool for identifier resolution. However, it does not explicitly mention when not to use it or suggest alternatives, though no sibling tool directly competes.

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 idempotent, read-only, non-destructive, and open-world. The description adds useful context about returned fields (UEI, CAGE, etc.) 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?

Extremely concise: one sentence stating the purpose followed by a bullet list of return fields. No wasted words.

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

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

With an output schema available and clear description of inputs and outputs, the tool is fully understandable. 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 descriptions for all 5 parameters. The description adds no additional parameter-level detail beyond summarizing the tool's purpose, so baseline score applies.

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

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

The description clearly states 'Search registered federal contractors by business name or UEI' and lists returned fields, distinguishing it from sibling tools focused on 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 for contractor search but lacks explicit guidance on when to use this tool instead of alternatives like sam_search_opportunities or other 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds listing of returned fields but doesn't disclose additional behavioral traits like rate limits or data freshness.

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?

A single sentence that efficiently conveys the tool's purpose and key return items, with no wasted words or unnecessary details.

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 parameter count (2), rich annotations, and presence of an output schema, the description adequately covers what the tool does and what it returns, 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% and both parameters are clearly described in the schema. The description adds no extra semantics beyond what the schema provides; baseline 3 applies.

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

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

The description uses a specific verb ('Get full details') and resource ('federal contract opportunity by solicitation number'), clearly distinguishing it from sibling search tools like sam_search_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?

It clearly states the tool is for looking up details by solicitation number, implying it's for specific lookups not searches. However, it doesn't explicitly contrast with sibling search tools or provide exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by explaining the default date range and alias behavior. No contradictions.

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

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

Three sentences, each adding essential information: purpose, date range requirement with defaults, and alias acceptance. No redundancy, well front-loaded.

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

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

Covers inputs, outputs (titles, solicitation numbers, deadlines, agencies), default behaviors, and aliases. Pagination is in schema. With output schema present, return values are documented. Complete for a search tool.

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

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

Schema coverage is 100%, so each parameter is described. The description adds context about the date range dependency and alias relationships, which goes beyond individual parameter descriptions.

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

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

The description clearly states it searches active federal contract opportunities by multiple criteria (keyword, NAICS, set-aside, date range, procurement type). It lists the resources and verbs, and distinguishes from siblings like sam_entity_search and sam_get_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?

Provides context on SAM.gov's requirement for a posting date range and explains the default behavior (last 30 days). Also notes aliases for keyword. Does not explicitly compare to sibling tools or state when not to use, but the context is helpful.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds return value context (titles, deadlines, agencies) but no 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?

Single sentence with parenthetical list; front-loaded with purpose. 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?

Returns fields are noted, but missing differentiation from sam_search_opportunities. Schema covers parameters, but absence of usage guidance reduces completeness.

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

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

Schema coverage is 100% with parameter descriptions, so baseline is 3. The description does not add parameter-level meaning beyond what the schema provides.

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

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

The description clearly states the verb 'Find' and the resource 'federal contracts reserved for small businesses', listing specific set-aside types. It distinguishes this tool from siblings like sam_search_opportunities by focusing on set-aside contracts.

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

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

No guidance is provided on when to use this tool versus siblings like sam_search_opportunities. The description does not mention alternatives or exclusion 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 indicate read-only, open-world, idempotent, non-destructive behavior. Description adds useful behavioral context: it probes each entity with 'ai_visibility_check', ranks by score, and surfaces most/least recognized. 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 two sentences, front-loaded with the main purpose, then details. Every word earns its place; no fluff 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?

No output schema exists, so description must explain output. It does: 'ranked list with score, confidence, signal density per entity.' Input constraints (entities: 2-8) are implied but not explicit. Overall 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% so baseline is 3. Description adds value: explains that first 'entity' is the subject, that 'context' disambiguates common names, and that 'models' defaults to 'workers-ai' while '_apiKey' is only needed for Anthropic. This helps the agent beyond schema alone.

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

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

Description clearly states it compares AI visibility across multiple entities, uses specific verb 'compare' and resource 'AI visibility', and distinguishes from the sibling 'ai_visibility_check' which is single-entity. The purpose is specific and unambiguous.

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

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

Description provides explicit context: 'useful for competitive AI-marketing audits' with an example question. It does not explicitly state when not to use or list alternatives, but the context is sufficiently clear for an agent to infer appropriate usage.

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

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

Annotations indicate safe, idempotent, read-only behavior. Description adds valuable behavioral context: fans out to external services, partial failures degrade gracefully (bundlephobia timeout handling), and lists what returns even on failure. No contradiction with annotations.

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

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

Description is slightly long but efficiently front-loaded with purpose. Each sentence adds value; minor redundancy like 'NPM ecosystem only' could be tighter, 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?

Given complexity (composite check with multiple services) and no output schema, description is remarkably complete: explains return fields, ecosystem scope, partial failure behavior, and links. Fully equips the agent 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%, but description adds meaning: scoped packages accepted, version defaults to latest. This clarifies usage beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: a composite check for deciding whether to add an npm package, covering license, advisories, version history, and bundle size. It distinguishes from sibling tools, none of which offer similar functionality.

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 when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also clarifies NPM-only scope and directs to deps.dev for other ecosystems, preventing misinvocation.

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: embedding model (BGE-base-en), window size (500-char overlapping), truncation cap (200K chars with flag), and output offsets. Annotations already state idempotent and read-only; 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?

Efficient, well-structured: starts with purpose, then usage, then pairing, then technical details. Every sentence adds value, no redundancy.

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

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

For a tool with no output schema, description covers output format (passages with offsets and scores), constraints (200K char cap), and pairing. Fully explains behavior for effective agent usage.

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

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

Schema coverage is 100%, so baseline is 3. Description enriches by explaining 'text' as fetched content, 'query' as natural-language, and 'limit' as top-N passages. Also describes output with offsets and scores, compensating for lack of output 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?

Clear verb 'search inside' with specific resource (fetched record) and examples (SEC 10-K, article). Distinct from siblings like 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 states when to use (when record too large for prompt) and pairs with ask_pipeworx_grounded for grounding. Provides clear context for selection.

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

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

While annotations set idempotentHint=true, the description does not clarify idempotency behavior (e.g., what happens if you subscribe to the same alert twice). It does mention the SMS 10/day cap and webhook auto-disable, but lacks details on subscription creation limits or duplicate handling.

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

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

The description is a single, dense paragraph that conveys all necessary information without extraneous text. For its complexity, it is fairly concise, though bullet points could improve readability.

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

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

Given the tool's complexity (nested objects, multiple types, delivery channels), the description covers all aspects: prerequisites, type-specific parameters, delivery constraints, and return value. It is complete for the agent to use the tool correctly.

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

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

The schema has 100% coverage, but the description adds significant value by explaining each subscription type's parameters with examples, and detailing delivery options including webhook signing and phone verification. This enriches the agent's understanding beyond the schema.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes itself from siblings like list_subscriptions and unsubscribe.

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

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

The description explains the prerequisite of a Pipeworx OAuth account, lists supported subscription types with examples, and describes delivery channels. It does not explicitly compare to alternatives but provides clear context for when to use the tool.

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

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

Annotations already cover safe, idempotent, non-destructive behavior. Description adds context about return format (category-bucketed examples with exact tool+argument shape) and that it draws from a live catalog, enhancing transparency 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 and front-loaded with common queries, but slightly verbose. Every sentence adds value, so it's efficient for the complexity.

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

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

Given the tool's purpose as an onboarding guide with a single optional parameter and no output schema, the description fully covers what it does, when to use it, and what it returns, leaving no gaps.

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

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

Schema coverage is 100% with a clear description. Description expands on the optional 'topic' parameter with examples ('finance', 'pharma') and explains omission gives a cross-category spread, adding significant value.

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

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

The description clearly states the tool as an onboarding entry point, returning category-bucketed example questions. It distinguishes it from sibling tools like 'ask_pipeworx' and 'discover_tools' by specifying it is for 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 says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and 'to learn how to call the meta-tools', providing clear context and when to use it.

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

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

Beyond annotations (destructiveHint=false), the description reveals that the row is deactivated, not deleted, and that ownership is enforced. This adds valuable behavioral context.

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

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

Two sentences, each essential. Front-loaded with action and resource, then constraint and behavior.

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

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

Given the simple single-parameter tool with no output schema, the description covers purpose, constraints, and side-effects completely.

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

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

Schema coverage is 100% and the schema already describes the parameter as 'Subscription id (uuid) returned by subscribe.' The description adds no additional meaning beyond the schema.

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

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

The description clearly states the action ('Cancel a subscription') and the resource ('by id'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use. However, it does not explicitly mention when not to use or alternatives.

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

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

Beyond annotations (readOnly, idempotent, etc.), description discloses return format (verdict, extracted structure, actual value with citation, percent delta) and notes it replaces 4-6 sequential calls. 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?

Description is well-structured with front-loaded trigger phrases. Each sentence adds value, though it could be slightly more concise. No wasted words.

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

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

With no output schema, the description fully explains return values and supported domain. It covers scope limitations (v1 company-financial claims) and usage context, making it complete for agent selection.

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

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

Schema description coverage is 100% and the schema already explains the claim parameter well. The tool description adds minimal additional meaning beyond paraphrasing the schema, so baseline 3 is appropriate.

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

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

Description clearly states tool validates natural-language claims against authoritative sources, specifically company-financial claims via SEC EDGAR + XBRL. It includes trigger phrases and example queries, and distinguishes from siblings as no other tool provides claim verification functionality.

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

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

Description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the domain (company-financial claims). It implies limitations (v1 supports only public US companies) but does not explicitly state when not to use or list alternatives, though siblings offer no comparable function.

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