Yc Rejection

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds context about the default free model, BYO key for Anthropic, and the return structure, complementing but not contradicting annotations.

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

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

The description is two sentences, front-loaded with the core action and outcome, with no unnecessary words. Every sentence adds essential information.

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

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

Given no output schema, the description fully explains return values (per-model object with score, confidence, signals, raw_response, plus combined view) and the scoring range (0-100), covering all needed context for an agent.

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

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

Schema coverage is 100% with detailed descriptions. The description adds value by explaining the '_apiKey' parameter's payment model and the 'context' parameter's disambiguation role, enhancing the schema's guidance.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility 0-100 per model, distinguishing it from sibling tools like 'scan_competitor_ai_presence' by focusing on generic entity visibility across models.

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: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the Anthropic API key versus the free default, providing 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?

Annotations already declare the tool is read-only, idempotent, and safe. The description adds value by explaining that it routes to 3,745 tools, fills arguments, and returns structured answers with pipeworx:// citation URIs, which clarifies behavior 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 concise, front-loads the key directive ('PREFER OVER WEB SEARCH'), then lists domains and examples. Every sentence serves a purpose, though it could be slightly tighter.

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 broad scope of the tool, the description covers purpose, usage, and behavioral traits well. It mentions return format (structured answer with citations) despite no output schema, and handles parameter semantics. Adequate for 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% with all parameters described as aliases for 'question'. The description confirms it accepts natural language and gives examples but does not add significant 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 tool answers factual questions using many authoritative data sources, with specific verbs ('ask'), resource ('Pipeworx'), and explicit preference over web search. It distinguishes from siblings by highlighting structured data with citations.

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

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

Explicitly advises when to use ('PREFER OVER WEB SEARCH') and provides detailed examples of query types. It does not explicitly exclude alternative tools, but the guidance is strong enough for correct invocation.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details how it picks the right tool, extracts the answer from tool results, and returns explicit refusal reasons. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the core purpose. It is slightly verbose but every sentence adds meaningful information. Could be trimmed slightly but remains efficient.

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

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

Given the complexity and absence of an output schema, the description fully explains the return format ({answer, evidence, confidence, ...}) and all possible refusal reasons, making the tool's behavior completely predictable.

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 'question.' The description adds that the parameter accepts 'natural language' and lists the aliases, which is helpful but already implied by the schema. Minor extra 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 it is a 'Hallucination-resistant answer mode for high-stakes reads,' specifying the verb 'ask' and the resource 'Pipeworx.' It distinguishes itself from the sibling 'ask_pipeworx' by highlighting the grounded, extractive behavior.

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: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and gives examples. It also advises preferring 'ask_pipeworx for casual lookups' and mentions the extra cost.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds extensive behavioral details: resolution contract, parent event extraction, news fields, safety short-circuits, closed market handling, wide spread warnings, and resolution-rule risk. No contradiction with annotations.

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

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

The description is detailed and well-structured with clear sections, but it is lengthy. It front-loads the main purpose and uses examples. Some parts could be more concise without losing essential information, but the complexity of the tool justifies the length.

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

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

Despite no output schema, the description thoroughly explains the response shape (result.market, result.analysis, result.evidence) with key fields. It covers edge cases (low-confidence, closed markets, wide spreads) and safety mechanisms, making it complete for an AI agent to effectively use the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value: explains market parameter format with examples, depth options with clear semantics, and include_raw with practical advice. This greatly enhances understanding beyond the schema.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data. It provides example use cases like 'should I bet on X' and distinguishes itself from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on comprehensive data retrieval and analysis.

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

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

Explicitly states when to use ('should I bet on X', etc.) and the input types (slug, URL, question). It also describes behavior for various scenarios (low-confidence, closed markets) but does not provide explicit when-not-to-use or direct alternatives among siblings.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds significant depth: explains data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. This goes well beyond annotations.

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

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

The description is a dense paragraph with multiple sentences, each adding unique value. It is slightly long but efficient given the complexity of the tool. Could be broken into shorter sentences or bullet points, but remains effective.

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

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

Despite no output schema, the description fully explains return data (line items per company/drug, citation URIs, sorting). For a tool with 2 straightforward parameters and no nested objects, the description covers all necessary context for correct invocation.

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

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

Schema coverage is 100% (both parameters described). The description adds rich semantics: 'type' maps to specific data sources and fields (company pulls 10-K metrics, drug pulls FAERS/trial counts); 'values' explains required format (tickers/CIKs vs drug names) and limits. This provides meaningful guidance beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs, with specific verbs like 'compare', 'rank', 'head to head'. It distinguishes from sibling tools by explicitly preferring this over sequential lookups and naming the alternative pattern.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups' and lists example queries. It gives context for when to use, but does not specify when not to use or mention any prerequisites, though the context is strong.

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

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

Discloses behavioral traits beyond annotations: parallel routing, evidence extraction, gaps for unanswered facets, 15-60s duration, and never-invented guarantee. Annotations already mark readOnly, openWorld, idempotent; description adds operational detail without contradiction.

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

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

The description is detailed but efficiently front-loaded with purpose. Could be slightly more concise, but every sentence adds value, covering behavior, use cases, requirements, and output format.

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

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

Despite no output schema, the description thoroughly explains output fields (evidence, confidence, source, gaps) and expected behavior. Combined with high annotation coverage, it is fully actionable 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 already provides full coverage (100%) with descriptions for both parameters. The description adds context about depth-plan linkage and expected response time, slightly 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 tool performs 'grounded multi-source research in ONE call' with decomposition and parallel routing, distinguishing it from siblings like ask_pipeworx for single lookups.

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

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

Explicitly guides when to use this tool (broad/multi-part questions) vs. ask_pipeworx, and mentions prerequisites like a Pipeworx account 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 mark it read-only and idempotent. Description adds that results include full schemas with examples and are ready to call, which is valuable 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?

Four information-dense sentences with front-loaded purpose. No wasted words; every sentence adds distinct value (purpose, examples, return details, usage guidance).

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

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

Despite no output schema, description fully covers return structure (names, descriptions, schemas, examples), usage context, and parameter flexibility. Complete 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 has 100% coverage with descriptions. Description adds context about aliases (e.g., task, q) and provides examples that were also in schema, but the aliases info is extra value.

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

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

Clearly states it finds tools by describing data/task, lists example domains, and distinguishes itself as a meta-discovery tool (not a data-retrieval tool like siblings).

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

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

Explicitly advises to call this first when many tools exist and you need to browse options—good guidance. Could mention when NOT to use it (e.g., if you already know the tool), but still 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds detail: fans out across multiple sources, soft-fails on patents (USPTO sunset May 2025), fallback from GDELT to GNews, and return structure including specific fields. No contradiction with annotations.

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

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

Front-loaded with example queries, then usage guidance, then detailed behavior. Slightly verbose with internal pipeline details (e.g., 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated') which could be shortened, but overall well-structured.

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

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

Given 2 parameters and no output schema, description provides comprehensive context: returns specific fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), data sources, and fallback mechanisms. Covers edge cases and limitations.

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

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

Schema coverage is 100%, baseline 3. Description adds value beyond schema: clarifies type enum (only 'company' currently), explains value must be ticker or zero-padded CIK, notes names are unsupported. Good context but schema already covers basics.

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

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

Description uses specific verbs like 'profile', 'return', and 'fans out' to state it produces a full cross-source profile of a US public company. Distinguishes from siblings like resolve_entity by noting names not supported and that this tool is preferred over chaining single-pack 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 says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also states when not to use: names not supported, use resolve_entity first. Provides clear context and alternatives.

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

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

Description aligns with annotations (destructiveHint=true) and adds context about clearing sensitive data, beyond what annotations provide.

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

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

Extremely concise: two sentences, front-loaded with action, no unnecessary 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 tool with one parameter and no output schema, the description provides sufficient context including use cases and pairing guidance.

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

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

Schema already covers the only parameter ('key') with a description. The tool description does not add further parameter semantics beyond what 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?

Clearly states it deletes a memory by key, and distinguishes from siblings like remember and recall by specifying deletion.

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 scenarios when to use (stale context, task done, clear sensitive data), but does not explicitly state when not to use.

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

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

Annotations already declare idempotent, read-only, non-destructive behavior. The description adds procedural detail (fetches page, extracts title/description/key links, emits markdown) without contradicting annotations. It doesn't mention rate limits or auth, but annotations cover safety.

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

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

Four sentences, front-loaded with the main action. Every sentence adds value: what it does, how it does it, output format, use cases. 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 low complexity (2 params, no nested objects, no output schema), the description fully explains input, process, and output format. The output is described as 'single text blob ready to drop at site-root/llms.txt' which is sufficient.

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

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

Schema coverage is 100% and already describes both parameters. The description adds meaningful extra context: example URL format, default and max for max_links. This adds value beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifies the target users (AI crawlers), and describes the process (fetch, extract, emit). It distinguishes itself from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on generating the standard markdown file.

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

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

The description provides explicit use cases (getting client site indexed, drafting for own project, auditing competitor's AI visibility). It lacks explicit when-not-to-use or comparison with siblings, but the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by specifying the return fields and the default behavior (active subscriptions only, with optional include_inactive). 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: first states purpose and return fields, second provides usage guidance. Nothing extraneous and 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?

Given the tool's simplicity (one optional boolean parameter, no output schema), the description fully covers what the tool does, what it returns, and when to use it. Complete for the context.

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

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

The single parameter 'include_inactive' is well-described in the schema (100% coverage). The description does not add new information beyond implying the default of active subscriptions, which aligns with 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 lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). It is distinct from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises using this tool to review what you're monitoring before adding more or to find an id to cancel, providing clear context for 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?

The description adds significant behavioral context beyond annotations: it states the tool is free, doesn't count against quota, is rate-limited to 5 per identifier per day, and that the team reads digests daily. Annotations are neutral (no readOnly, destructive, etc.), so there is no contradiction. The description fully discloses behavioral traits.

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

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

The description is a single, well-structured paragraph. Each sentence serves a purpose: stating the purpose, giving use cases, providing a 'don't' instruction, and noting rate limits/quota. There is no redundancy or fluff. It is front-loaded with the core purpose.

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

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

Given the tool's simplicity (no output schema, 3 parameters with complete descriptions), the description fully explains how to use it. It covers the type, message, and context parameters with guidance on what to include. No gaps remain for an agent to misinterpret.

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% (all 3 parameters have descriptions), and the description adds meaningful context: it explains the enum values in detail (bug, feature, data_gap, praise), advises on how to use the 'context' object, and specifies message length limits (1-2 sentences, 2000 chars). This adds significant value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then breaks down into specific use cases (bug, feature/data_gap, praise). The verb 'tell' and resource 'Pipeworx team' are explicit. It is distinct from sibling tools, which are primarily research and query tools.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes a prohibition ('don't paste the end-user's prompt') and mentions rate limits. This makes the tool's intended use 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, idempotentHint=true, destructiveHint=false. Description adds valuable context: self-aggregating from CF analytics-engine, no PII, caching duration (5min-1h). No contradictions. Exceeds annotation baseline with meaningful extra info.

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

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

Two sentences plus bulleted list and a note about caching. Every sentence serves a purpose: main function, use cases, technical details. Front-loaded with core action. Zero waste.

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

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

No output schema, but description specifies return of 'top tools, top packs, and total call volume' with data tuple (pack, tool, count). Sufficient for an AI to infer output shape. Caching and window semantics explained. Minor gap: exact format not detailed, but acceptable given simplicity.

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

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

Schema coverage is 100% for the single parameter. Schema description already explains window options and their implications. Description mentions the same but adds no new semantic details. 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?

Clearly states it returns top tools, top packs, and total call volume over a recent window. Verb 'returns' and specific resources (tools, packs, call volume). Distinguishes from siblings like ask_pipeworx (Q&A) and discover_tools (tool discovery) by focusing on trending aggregation.

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

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

Provides three explicit use cases: discovering hot data sources, confirming popular canonical tool, and checking use case alignment. Does not include 'when not to use' or explicit alternatives, but use cases are specific enough to guide selection among siblings.

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

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

Description adds substantial context beyond annotations: monotonicity logic, Jaccard similarity threshold (0.30), partition filter (placeholder fraction >20% returns null), and fill check (realizable_edge_pp ≤ 0 means no trade). This discloses internal algorithms and constraints without contradicting annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is detailed but structured: requirement, purpose, two modes, semantic anchor, partition filter, response format, fill check. Front-loaded with the required parameter condition. Could be slightly more concise, but the complexity justifies the length.

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

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

Despite no output schema, the description explains the response structure (opportunities[], partition_check, fill_check). It covers input parameters, usage constraints, internal logic, and references sibling tool for further actions. An agent has enough to decide when and how to invoke the tool.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds meaning: provides concrete slug examples, clarifies that event accepts full URLs, and explains the cross-event mode's use of seed question. While the schema is adequate, the description's extra examples and mode differentiation are helpful.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (single-event and cross-event) and contrasts with sibling tools like polymarket_fill_risk. The verb 'find' is specific to analysis, not creation, aligning with readOnlyHint.

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: event mode 'recommended for a specific market' with slug examples, topic mode 'for cross-event scanning'. States requirement 'REQUIRES one of event or topic — call with no args fails.' Points to sibling tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' Clearly indicates when to use each mode and when to defer.

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

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

Annotations already declare readOnlyHint and idempotentHint, making safety clear. The description goes far beyond by detailing caching (1h at KV level keyed on all knobs), response structure (by_segment, fed_candidates, diagnostics), and edge-case handling (e.g., placeholder-slug filter). No contradictions with annotations.

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

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

The description is highly detailed and technically dense, providing thorough information. However, it is lengthy and might benefit from more concise phrasing. While every sentence adds value, the overall structure could be tightened for quicker agent parsing.

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

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

With 9 parameters, no output schema, and no nested objects, the description covers all bases: it explains response structure, diagnostics, tradeable-edge knobs, and caching behavior. It fully compensates for the lack of an output schema by detailing what each segment contains.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how parameters act as 'tradeable-edge knobs' (e.g., min_partition_leg_kelly filters thin partitions) and notes that caching is keyed on all knobs, which is useful context beyond the schema.

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

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

The description clearly states it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_kalshi_spread via its focus on model-driven and structural arbitrage opportunities, providing a specific verb and resource.

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

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

The description explicitly says "Built for 'what should I bet on today'" and explains that agents discover opportunities without paging. It also notes that Fed bets are excluded from ranking. However, it does not explicitly state when not to use this tool versus alternatives, missing some exclusion guidance.

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

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

Annotations indicate safe, idempotent read. Description adds significant behavioral context: return structure (tracked, expired, snapshot_dates), computation details (trend, decay_pp_per_day), limits (60-day TTL, data gaps meaning no scan), and edge cases (negative sign for SELL YES).

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

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

Well-structured with clear sections and front-loaded core question. Somewhat lengthy but each sentence adds value. Could be more concise, but effective for complex telemetry tool.

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

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

Despite no output schema, description fully explains return fields (tracked[] with time-series, expired[] with lifespan, snapshot_dates[]), limits, and data gaps. Adequately covers complexity for advanced users.

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

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

Input schema covers both parameters with descriptions (100% coverage). Description adds default values (14 days, '1wk'), clamping (2-30), and clarifies 'window' as snapshot family options (24hr, 1wk, 1mo), providing extra meaning beyond schema.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering 'how long has this edge existed and is it shrinking?' It differentiates from sibling polymarket_edges by focusing on time-series behavior rather than raw edge data.

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

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

Implicitly guides usage by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). Does not explicitly list when not to use or name alternatives, but context clarifies its purpose for decay analysis.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context beyond annotations: explains the two modes, required parameter constraints, output fields, and risks like forced directional risk. No contradiction.

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

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

The description is long but well-structured with clear sections (SINGLE-MARKET, BASKET) and imperative tone. The first sentence conveys the core purpose. All information appears necessary given the tool's complexity.

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

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

The description fully explains both modes, parameter semantics, output fields, and risk warnings. No output schema exists, so the description compensates well. It addresses the complexity of the tool and leaves no ambiguity about its use.

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

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

Schema description coverage is 100%. The description adds value by explaining default values, interpretation in different modes (e.g., 'size_usd interpreted as settlement notional S'), and the auto-detection behavior for side in basket mode. This goes beyond the schema's brief descriptions.

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

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

Description starts with a clear verb+resource statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes single-market and basket modes and differentiates from siblings like polymarket_arbitrage and polymarket_edges by stating when to use this tool.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about not capturable theoretical edges and the risk of unhedged directional positions, providing clear when-to-use and when-not-to-use guidance.

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

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

Adds extensive behavior details beyond annotations: two modes, response structure, safety fields, compatibility warnings, temporal alignment, skipped comparison counters. No contradictions with annotations.

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

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

Front-loaded core purpose, structured with sections. Slightly long but 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?

Very complete given complexity: explains all safety fields, edge cases, and return values despite no output schema. Covers compatibility warnings and limitations.

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

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

Schema coverage is 100% so baseline 3. Description adds meaning by explaining topic shortcuts and explicit parameters, and providing examples, going beyond schema.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket, with specific verb+resource. It distinguishes itself from siblings by focusing on cross-venue comparisons vs intra-venue tools like polymorphic_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?

Provides explicit usage modes (topic vs explicit) and warns that real spreads are rare and pre-mapped topics often return compatibility_warning. Could be improved by explicitly contrasting with 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 convey readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping to identifier (anonymous IP, etc.) and pairing with remember/forget, providing context beyond annotations.

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

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

Two sentences, efficiently conveying purpose, usage, and scope. 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 one optional parameter, no output schema, and annotations providing safety, the description covers purpose, usage, behavior, and parameter semantics adequately. No gaps for this tool's complexity.

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

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

Schema coverage is 100% with description for 'key' parameter. Description adds that omitting key lists all keys, which is not in schema description, adding 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?

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the verb (retrieve/list), the resource (saved values/keys), and distinguishes from siblings like remember and forget. Examples of use cases are provided.

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

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

Explicitly states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Mentions pairing with remember and forget. While it doesn't state when not to use, the context is clear and sufficient.

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

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

The description discloses that setting 'mark_read:true' flags events as read, which is a state change that contradicts the annotation 'readOnlyHint: true'. This is a direct contradiction as per the rubric, requiring a score of 1. Annotations already provide readOnlyHint, idempotentHint, etc., but the description adds a side effect that conflicts with the readOnlyHint.

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 concise 4-sentence paragraph with no wasted words. It front-loads the main purpose, then details return fields, filters, and side effects, followed by a note on polling and an alternative endpoint.

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

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

Given the tool has no output schema, the description adequately explains the return fields (source, citation_uri, raw event payload). It covers all 5 optional parameters, polling behavior, and provides an alternative access method. No gaps are apparent.

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

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

The input schema covers all 5 parameters with descriptions (100% coverage). The description adds meaning beyond the schema, e.g., explaining that 'since' means 'fired_at >= this time' and that 'mark_read' ensures subsequent calls only show newer events. This adds value but is not exceptional.

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

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

The description clearly states 'Pull fired events from your subscription feed' and specifies return fields and filtering options, making the purpose unambiguous. It distinguishes itself from sibling tools like 'recent_changes' by focusing on alerts from the subscription feed.

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 mentions that polling works fine and that the same feed is available via a URL for scripts and dashboards, providing some guidance on when to use this tool vs. alternatives. However, it does not explicitly compare with other sibling tools or discuss when not to use it.

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

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

Beyond annotations (readOnlyHint, etc.), the description details internal behavior: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-failure, and return structure with grouped changes and citation URIs.

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

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

Description is front-loaded with example queries, then concise functional statement, then detailed source behavior. Slightly long but every sentence is informative and well-organized.

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

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

Covers all essential aspects: multiple data sources, fallback logic, relative date parsing, return structure, and sibling tool differentiation. No output schema exists, but return format is described.

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 significant value: gives examples for 'since' (ISO date and relative shorthands like '7d', '30d', '1y'), clarifies 'value' accepts ticker or CIK, and notes 'type' is limited to 'company'.

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 provides a change feed for a company in a time window, with example queries that map to user intents. It distinguishes from sibling 'entity_profile' which offers static profiles.

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

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

Explicitly says when to use 'entity_profile' instead, gives multiple example queries, and explains the purpose in context. Provides clear guidance on when this tool is appropriate.

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

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

The description adds behavioral context beyond annotations by stating persistence differences between authenticated users (persistent) and anonymous sessions (24 hours). Annotations already indicate non-readOnly, non-destructive, and idempotent, which the description corroborates without contradiction.

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

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

The description is concise with four sentences, front-loading the core purpose and usage, and includes essential details without fluff.

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

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

For a simple save tool with two parameters and no output schema, the description covers purpose, usage, persistence, and retrieval pairing. Slight gap: no mention of return value, but not critical for a write operation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples for key (e.g., 'subject_property', 'target_ticker') and clarifying that value can be any text.

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 saves data for later reuse across conversations or sessions, specifying the verb 'Save' and resource 'data'. It distinguishes from sibling tools by mentioning pairing with recall and forget.

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

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

Provides explicit guidance on when to use: when discovering information worth carrying forward (e.g., tickers, addresses, preferences). It also explains scope via key-value pairs scoped by identifier and mentions pairing with recall/forget.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that each call 'cascades through several lookup endpoints internally' and 'replaces 2-3 manual lookups,' which is useful for understanding cost and performance. It also details return formats for each entity type, including citation URIs, covering what the tool actually does beyond annotations.

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

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

The description is well-structured: starts with examples, then states the core purpose, usage guidance, and type-specific details. It is somewhat verbose but each sentence adds value. Could potentially be tightened, but overall it is effective 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?

Given no output schema, the description fully explains return values for both entity types, including citation URIs. It covers inputs, outputs, and internal behavior. For a tool with two parameters and clear functionality, this is complete and self-contained.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value beyond the schema: it explains that 'type' can be 'company' or 'drug', and for 'value', it provides examples for each type and clarifies what inputs are accepted (e.g., ticker, CIK, name for company; brand or generic for drug). This adds meaning and helps the agent understand parameter 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 starts with concrete examples ('What's the ticker for...') and clearly states the verb 'resolve' and the resource ('user-spoken NAME to canonical/official identifier'). It distinguishes itself from sibling tools like 'compare_entities' by focusing on ID lookup. The supported types ('company', 'drug') are explicitly listed with their outputs.

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 tells the agent to 'Use FIRST whenever you have a name but need an ID.' This is a clear directive. It does not explicitly name alternative tools, but the purpose is specific enough that an agent would know when to choose it over siblings like 'entity_profile'.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already declare safety traits. Description adds internal behavior: probes each entity with ai_visibility_check, returns ranked list with score, confidence, signal density. No contradiction with annotations. Adds value beyond annotations.

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

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

Three sentences, front-loaded with action, no fluff. Every sentence adds value (what, how, example use case). Highly 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 tool with 4 params, no output schema, and sibling tools, the description covers all needed aspects: purpose, internal mechanism (probes ai_visibility_check), output format (ranked list with metrics), and usage context. Complete without the need for additional info.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description adds extra meaning: first entity treated as 'subject' for narrative, rest as competitors. This enhances the schema's information.

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+resource: 'Compare AI visibility across multiple entities side-by-side.' Distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison). Specific and actionable.

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 use case provided: 'competitive AI-marketing audits' and example question 'does Claude know about us as well as our competitors?' Implies when to use but does not explicitly state when not to use or contrast with alternatives. Good context but could be more directive.

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

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

Adds significant context beyond annotations: explains composite nature, fan-out to two services, possible delay on first bundlephobia measurement, graceful degradation with sources_failed list, and return structure. 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 a single paragraph but efficiently conveys purpose, usage, return format, and limitations. Slightly dense but well-structured with clear sections. Could be more concise but earns its length.

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

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

Completes the picture for a complex composite tool: explains what is returned (summary fields, advisory details, links, alternatives), behavior under partial failures, and ecosystem scope. No output schema makes this essential, and it delivers.

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 'package' and 'version'. The description adds minimal extra: default version behavior and scoped package acceptance. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states the tool's purpose as a composite check for evaluating npm packages, specifying the verb 'scan' and the resource 'dependency'. It distinguishes from siblings by focusing on npm packages and integrating deps.dev and bundlephobia data.

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

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

Explicitly tells when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also notes NPM-only limitation and directs other ecosystems to use deps.dev:version directly. Provides timing caveats for bundlephobia's first measurement.

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, idempotentHint, etc.), the description discloses technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation, and character offsets for verification. No contradictions with annotations.

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

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

The description is a compact paragraph of 5-6 sentences, front-loaded with the core purpose, followed by usage guidance and technical details. Every sentence contributes meaning, with no redundancy or filler.

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

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

Despite lacking an output schema, the description adequately explains return values (passages with offsets and scores). It covers mechanism, limitations, and integration with a sibling tool, providing a complete understanding 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?

The schema covers all three parameters (100% coverage), but the description adds value by providing context (e.g., 'Pass the text you already pulled'), example queries, and explaining the limit as 'top-N passages'. This enhances understanding beyond the schema alone.

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

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

The description clearly states 'Semantic search INSIDE a fetched record', specifying the verb and resource. It distinguishes from sibling tools by contrasting with ask_pipeworx_grounded and emphasizing context-saving behavior.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and explains pairing with ask_pipeworx_grounded, providing clear context for when this tool is appropriate versus alternatives.

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

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

The description adds rich detail beyond annotations: auth requirements, type specifics, delivery channel constraints (SMS cap, webhook signing, auto-disable). 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 dense but well-structured with front-loaded purpose. Every sentence adds value, though it could be split for readability.

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

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

Covers all essential aspects: purpose, return value, auth, types, delivery channels, constraints. No output schema but return value is stated.

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

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

With 100% schema coverage, the description further elaborates on each type-specific parameter and delivery options, adding value beyond the basic schema descriptions.

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

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

The description uses a specific verb-resource pair ('Create a proactive monitoring subscription to a live-data event stream') and clearly distinguishes from sibling tools 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?

It explains necessary OAuth requirement and delivery channels, and mentions pulling via recent_alerts as an alternative. However, it does not explicitly state when to use this tool vs other subscription management 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, openWorldHint, idempotentHint, and destructiveHint. The description adds context by describing the return format (category-bucketed questions with tool calls) and the fact it draws from a live catalog, which is useful 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 relatively long but front-loaded with common queries and a clear purpose statement. Every sentence adds value, though a slight trimming of synonyms could improve conciseness without losing meaning.

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 and no output schema, the description fully covers what it does, when to use it, how to use it, and what results to expect. No gaps in understanding.

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

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

Schema coverage is 100% with a single optional parameter. The description adds examples of valid topic values ('finance', 'pharma', etc.) and explains the effect of omitting vs. providing the parameter, enhancing the schema description.

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

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

The description begins with common user queries ('What can I ask Pipeworx?', etc.) and immediately states that this is the onboarding entry point for a new agent. It specifies that it returns category-bucketed example questions with exact tool calls, clearly distinguishing it from other tools like ask_pipeworx.

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

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

The description explicitly instructs to use this tool FIRST when the agent does not know what Pipeworx can do. It also explains how to optionally pass a topic to focus and mentions meta-tools as 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?

Discloses that the row is deactivated (not deleted) and that historical events remain available, adding context beyond annotations. No contradiction with idempotentHint or destructiveHint.

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

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

Two concise sentences with no wasted words. Front-loaded with primary action, followed by key constraints and side effects.

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

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

Fully covers purpose, constraints, side effects, and related tools for a simple single-parameter tool. Agent has all needed context.

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

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

Schema already covers parameter id with description. The description adds ownership context relevant to using the parameter correctly, slightly enhancing beyond schema.

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

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

Clearly states 'Cancel a subscription by id' - a specific verb and resource. Distinguishes from siblings like subscribe and list_subscriptions by the cancellation action.

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 ownership enforcement ('you can only cancel your own subscriptions'), indicating when to use and when not. Also explains deactivation vs deletion, linking to recent_alerts as alternative for history.

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

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

Annotations declare read-only, idempotent, non-destructive behavior; description adds return format (verdict, structured form, citation, delta) and scope limitation (v1 supports only company-financial claims), providing useful behavioral context beyond annotations.

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

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

Description is moderately concise, front-loaded with example queries, and covers key aspects. A few redundant phrases 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?

For a single-parameter tool with no output schema, the description fully explains inputs, outputs, and scope. The agent has enough context to invoke correctly.

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

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

Only one parameter 'claim' with full schema coverage (100%). The description provides natural-language examples but does not add significant meaning beyond the schema's description. 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 defines the tool as a fact-checker for natural-language claims, with specific examples and scope (company-financial claims), and distinguishes it from siblings by noting it replaces multiple sequential calls.

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

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

Explicitly states when to use ('whenever the agent needs to check factual correctness') and provides claim examples. Lacks explicit when-not-to-use or direct alternative comparisons among siblings, but the specialized scope implies limits.

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 it as safe, read-only, idempotent, and non-destructive. The description adds 'instant' and clarifies the insincere encouragement, but no additional behavioral context beyond what annotations cover.

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?

At two sentences, it is concise and front-loaded. Each sentence adds value, though more detail on parameters could be added without losing conciseness.

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

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

Despite an output schema existing, the tool's 6 parameters lack explanation. For a low-complexity tool, the description is incomplete and requires external examples to understand inputs.

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 0% and the description does not mention any of the 6 parameters (e.g., idea, traction, pivot_count). Users must rely on examples, which is insufficient.

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 instant YC rejection for startup ideas, with a humorous insincere encouragement. It uniquely distinguishes from serious sibling tools like 'deep_research' 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?

No guidance on when to use or avoid this tool. While it's implied as a fun quip, there is no explicit context or exclusion criteria.

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