Could Have Been Email

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds important context: free default model, Anthropic requires BYO key and direct payment, returns per-model details. 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 sentences plus a use-case line. Front-loaded with the main action. Every sentence adds value with 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?

Despite no output schema, description explains return format per model (score, confidence, signals, raw_response) and combined view. Sufficient for a moderately complex tool with good annotations.

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

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

Schema coverage is 100%. Description adds value by explaining default model behavior, the effect of '_apiKey' (required for Anthropic probe), and how 'context' helps disambiguate. Exceeds baseline of 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?

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the default model and distinguishes from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on multi-model visibility scoring.

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

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

Provides context for when to use: AI-marketing audits, pre-launch brand checks, competitive monitoring. Does not explicitly mention when not to use or alternatives, but the stated use cases are clear enough.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that it routes to 3,745 tools and returns structured answers with stable citation URIs. Could mention error handling or ambiguous queries.

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 key instruction to prefer over web search. The bullet list of examples is helpful but somewhat lengthy. Every sentence contributes, but could be slightly more condensed.

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, description adequately covers output format (structured with citations). Covers many use cases. Lacks details on failure modes or limits, but sufficient for agent decision-making.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by listing aliases and providing natural language examples, showing how to phrase questions effectively.

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

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

The description clearly states the tool answers factual questions by routing to many authoritative sources, and explicitly distinguishes it from web search. It provides specific examples of queries it handles.

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 instructs to prefer over web search, lists dozens of concrete example query types, and gives sample questions. Clear when to use; omissions for when not to use are minimal given the broad scope.

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 behavioral details beyond annotations: same routing as ask_pipeworx, extracts answer using only tool result, returns specific refusal reasons. Annotations already indicate safe read and open world, description expands on mechanism. 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?

Front-loaded with key purpose and usage guidance. Every sentence adds value, though the block of text could be slightly more structured (e.g., bullet points). Still efficient and clear.

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

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

No output schema, but description fully explains return structure (answer, evidence, confidence, source, fetched_at, refusal_reason:null) and lists possible refusal reasons. Complete for a complex tool with 6 parameters and no output schema.

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

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

Schema coverage is 100% with all 6 parameters documented as aliases for natural language question. Description adds that it accepts natural language question and aliases, but this adds minimal value beyond schema. Baseline 3 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 hallucination-resistant answer mode for high-stakes reads. It specifies the verb (answers via grounded extraction), the resource (same routing as ask_pipeworx), and differentiates from sibling tool ask_pipeworx (casual lookups).

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

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

Explicitly states when to use (high-stakes reads, when answer will be quoted/cited/acted on, must not invent facts) and when not (casual lookups, prefer ask_pipeworx). Also mentions cost tradeoff.

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 is exceptionally transparent, detailing fan-out logic, response shapes, resolver contracts, parent event extraction, news fallback, safety short-circuits for low-confidence and closed markets, and resolution-rule risk. Annotations are consistent and add 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 relatively long but well-structured with clear sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.) and front-loaded with the main purpose. It is efficient in that every sentence adds value, though some details could be 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?

The description is comprehensive, covering all aspects of tool behavior—inputs, processing, outputs, edge cases, and safety mechanisms. Despite the lack of an output schema, the description effectively explains return values and response structure, making the tool complete 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?

All three parameters are fully described in the schema (100% coverage). The description adds meaningful context by explaining input formats for market, depth options with examples, and include_raw's impact on response size. This goes beyond the schema, providing agent-friendly 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 researches Polymarket bets by pulling Pipeworx data, with specific input types and use cases. It provides good purpose clarity but does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description gives usage examples like 'should I bet on X' and 'what does the data say about Y', and provides some context on when to inspect match confidence. However, it lacks explicit guidance on when not to use the tool or how it compares to alternatives, leaving room for improvement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds specifics: pulls latest 10-K data from SEC EDGAR/XBRL for companies (with off-calendar handling), FAERS data for drugs. It also mentions return format (sorted by primary metric, citation URIs). No contradictions.

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

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

Every sentence is informative. Front-loaded with example queries. No redundancy. Appropriate length 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?

No output schema, but description explains return structure (paired data, sorted, citation URIs). Mentions efficiency benefit. Covers all necessary aspects for a two-param 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%, baseline 3. Description adds significant value: explains enum values in detail, gives examples for values parameter (tickers for company, names for drug), and describes behavior differences per type. Exceeds baseline.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific examples of query patterns. It distinguishes itself from sequential single-pack lookups, which are sibling tools like 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries. It gives clear context on when to use this tool vs alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds transparency by listing the specific outputs (filler word count, decisions, action items, suggested email), which helps the agent understand the tool's 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?

Two clear, front-loaded sentences with no wasted words. Every sentence conveys essential information: the purpose and the return type.

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

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

The description adequately covers the tool's function given the presence of a full input schema and output schema. It mentions the return values, so the agent can infer what to expect. No major 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%, so the baseline is 3. The description does not add additional meaning to the parameters; they are already well-documented in the schema. The description focuses on outputs, not inputs.

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

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

The description states the specific verb 'Check' and the resource 'meeting transcript', clearly defining the tool's purpose. It distinguishes itself from sibling tools by focusing on email replacement 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?

No explicit when-to-use or when-not-to-use guidance is provided. However, the tool's purpose is narrow and unique among siblings, so usage context is implied but not detailed.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds valuable behavioral details: never invents answers (explicit gaps[]), returns pre-verified facts with citations, and mentions expected response time (15-60s). 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 relatively long but front-loaded with the core purpose. Every sentence adds necessary context (parallel decomposition, citations, gaps, time, requirements). Minor tightening possible but remains effective and informative.

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

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

Given complexity (multi-source research, decomposition, citations) and no output schema, the description adequately informs the agent about the return format (structured findings packet, pre-verified facts, gaps) and runtime expectations. Also covers account and payment requirements.

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 meaning beyond schema: explains depth enum values (quick=3, standard=5, thorough=8) and the paid plan requirement for thorough. For question, clarifies broad/multi-part queries are acceptable.

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

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

Description clearly states the tool performs grounded multi-source research by decomposing questions into sub-questions, routing to many tools/sources in parallel, and returning a structured findings packet. It distinguishes itself from sibling ask_pipeworx by noting it is for broad/multi-part questions while ask_pipeworx is for single lookups.

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

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

Explicitly states when to use (broad/multi-part questions) and when not to (single lookups, suggesting ask_pipeworx as alternative). Also notes prerequisites: Pipeworx account and paid plan for 'thorough' depth, providing clear context for agents.

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 behavioral context by explaining the return format ('top-N most relevant tools with names, descriptions, and full input schemas with curated examples') and stating that results are 'ready to call directly, no second schema lookup needed.' This exceeds annotation coverage 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 (two paragraphs) and well-structured. The first sentence defines the core function. The second sentence lists data domains and clarifies the tool is for discovery. The third sentence details return value and usage guidance. Every sentence adds distinct value with 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?

Given the large set of sibling tools (30+), the description adequately explains what the tool returns (top-N relevant tools with schemas). It does not detail ranking methodology or behavior at limits, but for a discovery meta-tool this is sufficient. The absence of an output schema is acceptable as the tool returns tool definitions.

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%, yet the description adds value by explaining that the 'query' parameter accepts synonyms like task, q, search, and description, and by providing natural language examples. This clarifies usage beyond the schema's property 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: 'Find tools by describing the data or task.' It specifies the action (discover), the resource (tools), and provides concrete examples of data domains (SEC filings, financials, etc.). The description distinguishes this tool from sibling tools that perform specific data queries (e.g., search_within) by framing it as a meta-search to discover available tools.

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

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

The description explicitly advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use the tool. However, it lacks explicit exclusions or direct comparisons to alternatives, which would strengthen the guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it fans out across multiple sources, returns up to 5 filings, and notes that USPTO patents 'soft-fails until reactivated' due to API sunset. 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 but well-structured, starting with example queries, then explaining the action, and listing return fields with formatting. It efficiently conveys necessary information without unnecessary verbosity.

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 (2 parameters, no output schema, multi-source return), the description is complete. It lists all return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and notes limitations (patents soft-fail, only company type). An agent can understand the full output without ambiguity.

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 beyond the schema by providing examples ('Pass ticker "AAPL" or zero-padded CIK'), clarifying that names are not supported, and reiterating the type constraint. This helps the agent understand usage beyond 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 the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and lists the sources and return fields. The verb 'profile' and resource 'entity' are specific. Distinguishes from 'resolve_entity' by noting name resolution prerequisite.

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 that names are not supported, directing users to use 'resolve_entity' first. Provides 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?

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds minimal context beyond 'delete' and 'clear sensitive data', but no contradiction or deeper behavioral detail.

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

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

Two sentences, front-loaded with purpose, no wasted words. Each sentence earns its place.

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?

Simple tool with one parameter, schema covers it, annotations cover destructive behavior. The description covers when to use, but could mention return value or confirmation. Still sufficient for simple deletion.

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 'key' described as 'Memory key to delete'. The description does not add additional meaning beyond the schema, so 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?

The description clearly states it deletes a memory by key, with specific verb and resource. It distinguishes from siblings by naming remember and recall, and provides usage scenarios.

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 when-to-use scenarios (stale context, task done, clear sensitive data). Does not include when not to use, but alternatives are implied by pairing with remember and recall.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that the tool 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' which aligns with these hints. However, it doesn't reveal additional behavioral traits beyond what annotations convey. Since annotations cover safety well, the description adds minimal extra transparency.

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

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

The description is concise and well-structured: first sentence states core purpose, second explains process, third lists use cases. Every sentence adds value with no fluff. It is appropriately front-loaded with the key action.

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

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

Given the low complexity (2 simple params, no output schema), the description adequately covers the tool's operation and outcome ('Output is a single text blob ready to drop at site-root/llms.txt'). It lacks details on error handling or edge cases, but for a straightforward generation tool this is sufficient. The annotations further complete the safety profile.

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 per guidelines baseline is 3. The description ('Full URL of the site to summarize' and 'Maximum number of link entries to include (default 25, max 50)') mirrors the schema descriptions exactly, adding no new meaning. It provides context for the tool's overall function but not for the parameters themselves.

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: 'Generate a production-ready llms.txt file for any URL so AI crawlers can index the site cleanly.' It uses a specific verb ('generate'), identifies the resource ('llms.txt file'), and explains the use cases. This distinguishes it from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence' which focus on analysis rather than file generation.

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 contexts for use: '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.' It doesn't explicitly state when not to use or list alternative tools, but the clarity of purpose makes the usage scope clear. A higher score would require 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 already declare read-only, idempotent, non-destructive. Description adds that it returns specific fields and defaults to active subscriptions, providing behavioral details 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?

Two concise sentences: first states action and return fields, second gives usage guidance. No wasted words, 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 list tool with one optional parameter, description covers return fields and usage. No output schema, but description adequately specifies what is returned. No mention of pagination, but likely implicit.

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 description for 'include_inactive'. Description does not add additional meaning beyond baseline, so score is 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?

Description states specific verb 'List' and resource 'the caller's active subscriptions', mentions returned fields, and distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicitly says when to use: 'to review what you're monitoring before adding more or to find an id to cancel'. Provides clear context for use relative to other subscription tools, though does not mention alternatives or 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 provide no hints (all false), so the description carries the burden. It adds rate-limiting (5 per identifier per day), free usage, and that the team reads digests daily. No contradiction with annotations.

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

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

The description is a single paragraph of 4-5 sentences, front-loaded with purpose. It is concise but could be more structured (e.g., bullet points). Every sentence adds value.

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

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

For a simple feedback tool with 3 parameters and no output schema, the description covers purpose, usage, parameter semantics, and behavioral constraints completely. No missing information.

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

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

Schema coverage is 100%, so baseline is 3. The description adds guidance on message content ('Describe the issue in terms of Pipeworx tools/packs') and clarifies the 'type' enum values briefly, providing 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 verb 'Tell' and the resource 'the Pipeworx team' with specific categories (bug, feature/data_gap, praise). It distinguishes from sibling tools by focusing on feedback rather than queries or 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?

The description explicitly lists when to use (bug, feature/data_gap, praise) and provides a negative guideline ('don't paste the end-user's prompt'). It mentions rate limits and that it's free, but does not explicitly compare to 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 readOnlyHint, idempotentHint, etc. Description adds useful context: self-aggregating from CF analytics, no PII, caching behavior (5min-1h). 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?

Concise three sentences plus bullet list. Every sentence adds value, no redundancy. Front-loaded with main purpose.

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

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

For a single-parameter tool with no output schema and clear annotations, description covers purpose, usage, parameter semantics, and behavioral notes. Sufficient for correct 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?

Schema coverage is 100% but description adds value by explaining meaning of window values: 'shorter windows surface what's hot right now; longer windows show steady-state demand.'

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 returns top tools, top packs, and total call volume over recent windows, distinguishing it from siblings like ask_pipeworx or discover_tools. Uses specific verb+resource structure.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tool, aligning use case). Provides context on when to use each window length.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds extensive behavioral context: it performs semantic anchor checks (Jaccard similarity), partition filters (placeholders), and a fill check against live CLOB depth, including a warning when realizable_edge_pp ≤ 0. 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 comprehensive and front-loaded with the requirement, but it is lengthy and includes detailed algorithmic explanations. While every sentence adds value, the length might be slightly more than ideal for quick scanning. Still, it is well-structured with clear sections.

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 explains the response structure (opportunities array, partition_check fields, fill check details). It covers edge cases (skipped_low_similarity, placeholder filtering, thin_legs). Since the tool returns complex arbitrage analysis, the description is remarkably 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 descriptions for both parameters. The description significantly enhances these by explaining the difference between event and topic modes, providing example slugs, and detailing what each mode does (walks child markets, searches related events). This goes far beyond the schema.

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

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

The description explicitly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between event and topic modes, and the verb 'find arbitrage opportunities' is specific to the resource Polymarket contracts. This clearly differentiates it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description provides clear when-to-use guidance: 'event (recommended for a specific market)' vs 'topic (for cross-event scanning)'. It explicitly states that calling with no arguments fails, and points to polymarket_fill_risk for custom sizing. This is excellent guidance for an AI agent to choose the correct mode.

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 caching, response structure (by_segment, diagnostics), model internals (FRED log-returns, GDELT, partition_overround with per-sport alpha), and filtering logic. It warns about 24h moves and explains why Fed bets are excluded, adding significant behavioral context.

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

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

The description is lengthy but well-organized with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and bullet points. It front-loads the purpose and uses efficient language, earning each sentence's place 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?

Given 100% schema coverage and no output schema, the description thoroughly covers the return structure (fields like edge_pp_net, kelly_fraction, market info) and top-level keys. It explains diagnostics and caching, making it largely complete for a read-only 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?

All 9 parameters are described in the schema, so baseline is 3. The description adds substantial rationale and usage advice (e.g., slippage_pp discusses market fees, min_partition_leg_kelly clarifies its specific purpose). This extra context justifies a score above 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings by specifying the Pipeworx data source and the discovery-oriented goal, differentiating from arbitrage or tracking 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?

It explicitly targets 'what should I bet on today' and mentions caching and knob usage. While it doesn't directly compare to sibling tools, it provides context on when to use (discovery) and what the tool excludes (Fed bets with unreliable data).

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 valuable context: it reads daily snapshots, returns time-series, trend classification, expired opportunities with lifespan, and notes that snapshots are written on cache-miss. 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 thorough but somewhat lengthy. It is front-loaded with the core question and provides structured details on response fields. While every sentence adds value, it could be slightly more concise without losing information.

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

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

Given the tool's complexity (time-series tracking, trend classification, expired opportunities, snapshot gaps), the description is comprehensive. Without an output schema, it fully explains the response structure (tracked[], expired[], snapshot_dates[]) and their fields, making it 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?

Input schema has 100% coverage with descriptions. The description adds meaning by stating defaults (days default 14, window default '1wk'), explaining window as 'snapshot family', and defining the context of lookback and max (days max 30). This goes beyond simply restating schema.

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

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

The description explicitly states it answers 'how long has this edge existed and is it shrinking?' and specifies it provides edge persistence and decay telemetry. It clearly distinguishes from siblings by focusing on time-series analysis of edge persistence rather than raw edge data or other polymarket 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 explains when to use the tool (to understand edge persistence and decay) and includes important limitations: history depth bounded by 60-day snapshot TTL, decay from daily closes, not intraday, and gaps indicate days without scans. It implicitly differentiates from siblings like polymarket_edges (raw snapshots) and polymarket_arbitrage.

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. The description adds significant behavioral context: explains the tool performs a live order-book depth check, returns specific fields (top_of_book, vwap_fill_price, slippage, verdict), and warns about thin books and directional risk. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). It is front-loaded with the core purpose. While slightly verbose, the complexity of the tool (two modes, many return fields) justifies the length. Could be trimmed slightly 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's complexity (two modes, no output schema), the description is remarkably complete. It details return fields for each mode, explains interpretation of results (capture_ratio, profit_usd, thin_legs), and warns about forced directional risk. It even provides usage context in relation to sibling tools and trade sizes.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains the dual modes (market vs event), the default side logic for basket mode, and interprets size_usd as settlement notional for baskets. It provides defaults and clamps (10–1,000,000), adding clarity.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by advising to use this tool before acting on their signals.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the risks of partial fills and unhedged positions, providing clear usage guidance.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description significantly extends transparency by detailing response structure (leg-by-leg prices, matched spreads) and safety fields (compatibility_warning with two cases, temporal_alignment, skipped counters). No contradiction with annotations.

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

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

The description is long but well-structured with clear sections for overview, modes, response, and safety fields. Every sentence adds value, though could be slightly more concise. It front-loads 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 complexity and lack of output schema, the description fully covers purpose, modes, response format, safety warnings, temporal alignment, and skipped counts. It provides all necessary information for correct tool invocation and interpretation.

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 has 100% coverage, so baseline is 3. The description adds value by explaining the two modes in detail, listing topic shortcuts, and clarifying that explicit parameters override topic-mapped sides. This goes beyond the schema descriptions.

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

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

The title and description clearly state the tool computes cross-venue spreads between Kalshi and Polymarket. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on inter-venue comparisons and mention of 'the same resolving question'. The verb 'cross-venue spread' and resource are specific.

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

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

The description explicitly defines two modes (topic shortcuts and explicit tickers), when to use each, and cautions that most pre-mapped topics return compatibility warnings. However, it does not explicitly state when not to use the tool or direct to alternatives like polymarket_arbitrage, though the caution implies low tradeability.

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?

Aligns with annotations (readOnly, idempotent, non-destructive). Adds transparency on scope (per identifier) and pairing with remember/forget for full lifecycle.

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, examples, 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?

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, behavioral context, and parameter semantics 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 provides 100% coverage for the parameter. Description adds real-world examples and functional behavior (omit key to list all).

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?

Describes both retrieval by key and listing all keys, distinguishes from siblings remember and forget, and gives concrete examples of when to use.

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?

Clearly states when to use (look up previously saved context) and how to switch modes (omit key for listing). Lacks explicit 'when not to use', but context is sufficient.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral details: returned fields (source, citation_uri, raw payload), effect of mark_read on subsequent calls, and that polling is acceptable. 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 concise (4 sentences), front-loaded with the main purpose, and every sentence adds necessary information without redundancy or 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 5 parameters, no output schema, and strong annotations, the description covers the core functionality (return fields, filtering, mark_read state) and mentions an alternative endpoint. It lacks details on default limit behavior (though schema specifies) and error handling, but is reasonably complete for the tool's 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% with individual parameter descriptions. The description adds value by explaining the effect of mark_read (flags events read so next call only shows newer ones) and providing a concrete example for type ('sec_8k'), going beyond mere schema repetition.

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

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

Clearly states the tool pulls fired events from the subscription feed and returns recent alerts. The verb 'pull' and resource 'subscription feed' are well-defined, distinguishing it from sibling tools like 'subscribe' which manage 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?

Provides clear context on filtering by type and since, setting mark_read, and mentions polling works fine. It also offers an alternative access method for scripts/dashboards, but does not explicitly exclude usage when other tools would be better.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds details: fans out to multiple sources in parallel, fallback from GDELT to GNews, USPTO soft-fail due to API sunset, and output format (grouped changes, total count, citation URIs). 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 efficient, front-loading examples and using inline bullet-like structure for sources. It could benefit from slightly more structure (e.g., line breaks), but no unnecessary sentences.

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

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

Given the tool's complexity (multi-source aggregation, fallbacks, soft-fail), the description is well-rounded. It explains source behavior, output, and caveats (USPTO soft-fail). Minor gaps like pagination or rate limits, but overall very 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 descriptions for all three parameters. The description adds value with examples for since (ISO and relative), recommended '30d' or '1m', and clarifies value accepts ticker or CIK. It also shows example queries.

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

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

The description clearly states the tool provides a change feed for a company in the last N days/weeks/months in one parallel call. It lists specific sources (SEC EDGAR, GDELT→GNews, USPTO) and gives example queries. It distinguishes from sibling entity_profile, which is for static profiles.

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

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

The description explicitly recommends using entity_profile for static profiles. It explains fallback behavior for news (GDELT preferred, GNews on rate-limit/5xx). It provides date format examples and a recommended since value. While not exhaustive, it gives clear context for when to use this tool.

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

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

Annotations indicate idempotentHint=true and no destructive behavior. The description adds valuable context: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This goes beyond annotations by explaining scoping and session persistence, which is crucial for understanding the tool's side effects.

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

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

The description is concise at 4 sentences, each adding distinct value. It front-loads the purpose in the first sentence. It could be slightly more structured (e.g., bullet points for examples), but it efficiently conveys all necessary information without waste.

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

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

Given the tool's simplicity (2 required params, no output schema), the description is thorough. It explains when to use, what to store, scoping, persistence, and pairing with related tools. It does not need to explain return values since it is a write operation. The description covers all essential aspects 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 description coverage is 100% for both parameters ('key' and 'value'), so the schema already provides clear meaning. The description does not add any additional parameter-level details beyond what the schema offers, so it meets the baseline but does not exceed it.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with specific verb and resource. It distinguishes from siblings by mentioning 'recall' and 'forget' and gives concrete examples (resolved ticker, target address, user preference), making it easy to understand 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?

The description provides clear guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also notes pairing with 'recall' and 'forget' for retrieval and deletion, implying when not to use this tool (e.g., for retrieval or deletion). However, it does not explicitly list alternative tools for similar purposes, but the sibling names are given separately.

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 reveals internal behavior: each call cascades through several lookup endpoints, replacing 2-3 manual lookups. It details the return fields for each type (e.g., company returns ticker, CIK, company_name, citation URI) and mentions auto-disambiguation. This adds significant value beyond the structured 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, starting with example queries to convey purpose, then a usage guideline, followed by detailed type specifications. While it is somewhat lengthy, each sentence serves a purpose and no information is redundant. It could be slightly more streamlined, but it remains effective.

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

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

Given the tool's complexity (two entity types, no output schema), the description adequately covers what the tool returns for each type and mentions internal cascading. It positions the tool as the entry point for name-to-ID resolution. However, it omits error handling, edge cases (e.g., ambiguous inputs), and the exact structure of the response. These gaps are minor given the tool's straightforward lookup nature.

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 provides descriptions for both parameters, but the description greatly enriches understanding. For the 'value' parameter, it gives specific examples (ticker, CIK, name for company; brand/generic name for drug) and explains auto-disambiguation. This adds critical context that the schema alone does not capture.

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

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

The description clearly states the tool's function: resolving user-spoken names to canonical identifiers. It provides concrete example queries like 'What's the ticker for...' and specifies supported entity types (company, drug). The instruction 'Use FIRST whenever you have a name but need an ID' distinguishes it from sibling tools, making its role 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?

The description explicitly advises using this tool 'FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also lists supported types and input formats. However, it does not explicitly state when not to use it or mention alternative tools beyond the implicit context of being the first step.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing a safe, non-destructive profile. The description adds value by revealing that the tool internally calls ai_visibility_check, and specifies the output structure: 'Returns ranked list with score, confidence, signal density per entity.' This goes beyond annotations to explain behavior. No contradictions found.

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 plus a bit, providing a clear overview and an example query without being overly verbose. The example question is helpful but slightly extends the length. Every sentence adds value, though a slightly tighter focus on essential operational details could improve conciseness.

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

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

Given the complexity (comparison across multiple entities) and the absence of an output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It also specifies entity count limits (2-8) and the role of the first entity. The description compensates well for the missing output schema, but a mention of error scenarios or behavior with invalid inputs could improve completeness.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds marginal value by noting that the first entity in 'entities' is treated as the 'subject' for narrative purposes. This is a subtle nuance not in the schema. However, the description does not elaborate on each parameter 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's purpose: 'Compare AI visibility across multiple entities side-by-side.' It uses a specific verb ('Compare') and resource ('AI visibility'), and explains the process ('probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized'). This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (likely different domain), making its purpose 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?

The description provides explicit context for when to use the tool: 'Useful for competitive AI-marketing audits' and includes an example question ('does Claude know about us as well as our competitors?'). It implies usage through the process description but does not explicitly state when not to use it or provide alternative tool recommendations. The sibling list is available but not referenced in the description. This is clear but not exhaustive, warranting a 4.

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 behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed reported. 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?

Effective front-loading of purpose and key details. Though somewhat long, every sentence adds value. A slightly tighter edit could improve, but it's 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 no output schema, the description fully describes the return structure (summary block, per-advisory, links, alternative versions) and failure modes. Complete for a complex multi-source tool.

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

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

Schema coverage is 100% and already explains both parameters. The description adds no new semantic information beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it's a composite check for npm packages, covering license, advisories, bundle size, etc. It distinguishes from siblings by specifying NPM-only and referencing deps.dev directly for other ecosystems.

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

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

Provides explicit usage scenarios: when agent asks about safety, popularity, size, or cost of adding a package. Also mentions bundlephobia delay and that non-NPM packages should use deps.dev directly. Could be stronger on exclusion but 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?

Discloses embedding model, chunking strategy, similarity metric, character limit with truncation flag, and passage offsets. Annotations already cover safety; description adds valuable implementation details.

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?

Dense but efficient: every sentence adds value, starts with purpose, and includes technical details without redundancy.

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

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

Covers all key aspects: use case, mechanics (embeddings, chunking, offsets), limitations, and sibling integration. No output schema, but return format is implied.

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 enhances with query examples, limit range/default, and text max length context. Slightly above 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?

Clear verb ('search within') and resource specified ('fetched record'), with concrete examples (SEC 10-K, article). Distinguished from sibling tools 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 ('record too big for prompt') and pairs with sibling tool (ask_pipeworx_grounded) for grounded Q&A.

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 indicate idempotentHint=true and openWorldHint=true, the description adds crucial behavioral traits: requires Pipeworx OAuth account, delivery channel constraints (SMS cap, webhook auto-disable after 10 failures), and that webhook secret is returned only once. No contradiction with annotations.

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

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

The description is well-structured with the purpose upfront, followed by types, then delivery options. It is comprehensive but could be slightly more concise by grouping constraints. 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 3 parameters, no output schema, and high complexity (multiple types with different params, multiple delivery options), the description covers all aspects: authorization requirement, type-specific param formats, delivery channel constraints, and behavioral notes. No obvious gaps for secure 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?

Although schema coverage is 100%, the description adds significant meaning by providing concrete examples for each type's params, constraints like phone verification requirement, and details on delivery channel behavior (e.g., webhook signing secret). This goes well beyond the schema's descriptions.

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream', and explicitly mentions the return value 'Returns the new subscription id'. This distinguishes it 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 provides guidance on when to use the tool by listing supported subscription types and delivery channels. It implicitly suggests alternatives like 'recent_alerts' for polling, but does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds functional behavior: returns categorized questions with exact tool calls, but doesn't mention response size limits or pagination, though not needed for this tool.

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 natural language queries but is somewhat lengthy (four sentences). However, every sentence adds value—no redundancy. Efficient for the information density.

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

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

Given the tool's simplicity (1 optional param, no output schema, rich annotations), the description covers all needed context: purpose, usage timing, output contents, and parameter options. 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 single optional 'topic' parameter. The description adds value by listing example topic values and explaining behavior when omitted, going beyond the schema's basic description.

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

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

The description clearly states the tool returns category-bucketed example questions with tool+argument shapes, and distinguishes it as an onboarding entry point distinct from sibling tools like ask_pipeworx or 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning to call meta-tools, providing clear when-to-use and alternative 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?

Describes deactivation vs deletion and mentions historical event availability, adding value beyond annotations. Annotations indicate mutating but not destructive; description clarifies exact behavior.

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

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

Two sentences, no fluff, key details 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 tool with one parameter and no output schema, the description covers purpose, ownership, side effects, and historical data retention adequately.

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 with full schema coverage. Description adds that id is 'returned by subscribe,' aiding 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?

Clearly states 'Cancel a subscription by id' – specific verb+resource. Distinguishes from siblings 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?

Notes ownership enforcement: 'you can only cancel your own subscriptions.' Adds clear context but does not explicitly state when not to use or name 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 goes beyond annotations (readOnlyHint, openWorldHint, etc.) by detailing the return values (verdict, structured form, actual value with citation, percent delta), the fact that it replaces multiple sequential calls, and the limitation to v1 supporting company-financial claims. No contradictions with annotations exist.

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 reasonably concise for the complexity, starting with example queries and a clear purpose. Every sentence adds value, though the list of example queries could be slightly trimmed without loss. Front-loaded structure helps quick comprehension.

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 sophistication (replaces 4–6 sequential calls, natural-language input, financial domain), the description is complete. It explains supported domain, return types, and limitations despite lacking an output schema. The description alone sufficiently guides 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 single parameter 'claim' has a schema description, but the tool description adds significant context by providing natural-language examples ('Apple's FY2024 revenue was $400 billion') and clarifying the expected format. With 100% schema coverage, the description enriches 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 uses specific verbs like 'fact check', 'verify', and 'confirm or refute', and clearly distinguishes the tool's role in natural-language claim verification against authoritative sources. It explicitly lists example queries and the supported domain (company-financial claims for public US companies), making its purpose unmistakable and distinct from sibling 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 states 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the scope (company-financial claims via SEC EDGAR + XBRL). It does not explicitly mention when not to use or list alternatives, but the context signals and sibling list indicate uniqueness. Minor gap remains for exclusion criteria.

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