Tavily

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond annotations: the free default model, the BYO-key cost implication for Anthropic calls, and the per-model return structure. No contradictions.

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

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

The description is three tightly packed sentences: purpose, key configuration, return format, and use cases. No filler or repetition of schema content. Front-loaded with the most important information.

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

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

Despite lacking an output schema, the description clearly explains the return structure ({score, confidence, signals, raw_response} + combined). It covers configuration, cost, use cases, and model selection, making it complete for a 4-param tool with strong 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%, so the baseline is 3. The description mentions the default model and _apiKey purpose, but these are already documented in the schema. It adds minimal extra parameter semantics beyond rephrasing what the schema states.

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 ('Probe') and clearly identifies the resource (LLMs) and the deliverable (visibility score 0-100 per model). It distinguishes itself from siblings like ask_pipeworx and deep_research by focusing on scoring AI knowledge about an entity rather than general Q&A 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?

It provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for when to use the tool, though it does not mention exclusions or explicit alternatives, which would merit a 5.

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, which the description does not contradict. It adds value by explaining the internal routing across 5,439 tools, the output format (structured answer with pipeworx:// citations), and the 'one fast call' performance characteristic.

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 every sentence serves a purpose: priority guidance, capability explanation, trigger phrases, examples, hierarchy to other tools, and limitations. It is front-loaded with the most critical directive ('PREFER OVER WEB SEARCH'), making it scannable despite 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?

Given the tool's complexity as a router to thousands of sources, the description covers all essential aspects: what it does, when to use, when not to use, examples, output format, and relationship to sibling tools. No output schema exists, but the description clearly indicates the deliverable (structured answer with citations).

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 six parameters documented as aliases for the question string, and the schema includes examples. The description does not need to add parameter details; it correctly focuses on usage context rather than repeating schema 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?

The description explicitly states that the tool routes factual questions to appropriate sources and returns structured answers with citations, making its purpose unmistakable. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by defining its role as the default entry point for broad factual queries.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE', and 'Step up only when needed' with named alternatives (ask_pipeworx_grounded, deep_research). It lists example queries and even clarifies when not to use it (breaking news vs. deep multi-part research).

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds valuable context about the experimental nature, live candidate testing, and the fact it's a full working router with no fallback. It doesn't contradict annotations, though it omits potential failure modes or rate limits.

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 informative but slightly redundant, repeating 'currently matches ask_pipeworx exactly' and 'same 5,439 tools, same arguments, same response shape'. Each sentence earns its place, but trimming would 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?

For a beta tool with experimental behavior, the description is very complete. It explains the current state, history, usage, and response shape (via 'same response shape' reference), covering what would otherwise be missing without an 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 description coverage is 100% with all 6 parameters documented, including aliases. The description only says 'same arguments' without additional parameter-specific insight, so it adds no 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 identifies this as a beta version of ask_pipeworx and a universal router, distinguishing it from siblings via its experimental nature. However, it lacks a direct imperative verb like 'ask' or 'route', relying on the name and context to convey the 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?

Explicit usage guidance is provided: use it exactly like ask_pipeworx when you want the newest routing. It also notes the current state (no active candidate) and compares against the stable router, making when-to-use unambiguous.

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 the annotations: it costs an extra LLM call, returns a refusal with specific reasons (not_in_source, no_tool_match, etc.) when data doesn't directly answer, and extracts only from tool results to avoid hallucination. This enriches the readOnly and idempotent hints already present.

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 every sentence earns its place: it states the purpose, explains the mechanism, details the return shape and refusal reasons, and gives usage guidance with a cost tradeoff. It is front-loaded with the high-level purpose and uses structured examples of refusal reasons, making it easy to scan.

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

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

The tool is complex, with no output schema, but the description fully covers return values (answer, evidence, confidence, source, fetched_at, refusal_reason) and refusal behavior. It also covers usage context, cost implications, and alternatives. Combined with the rich annotations and schema, the description is complete enough for an agent to use the tool effectively.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters (with five aliases and 'question'). The description does not add parameter-specific semantics beyond noting it accepts a natural language question, which is already in the schema. Baseline 3 is appropriate since the schema fully covers the parameters.

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 what the tool does: it is a hallucination-resistant answer mode that routes through the same pipeline as ask_pipeworx, fetches data, and extracts answers using only tool result content. It also distinguishes itself from the sibling tool ask_pipeworx by emphasizing grounded extraction and refusal behavior, making it easy to differentiate.

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.' It also provides an exclusion: 'prefer ask_pipeworx for casual lookups' and notes the cost difference (one extra LLM call). This gives clear guidance on when to choose this tool over alternatives.

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

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

Beyond the reliable annotations (readOnly, idempotent, non-destructive), the description discloses a wealth of behavioral traits: low-confidence matches short-circuit with status 'low_confidence_match', closed markets return 'market_closed_or_inactive', wide-spread markets carry 'illiquid_wide_spread', and the resolution-rule risk section explains how cancellation_rule parses void/postponement settlements. It even mentions the 24h-move warning. This far exceeds the annotation hints.

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

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

Although long, every sentence is information-dense and earns its place. The description is well-structured with clear section labels (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) and practical fan-out examples. This is appropriately sized for 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?

With no output schema, the description takes on full responsibility for documenting return values, and it does so comprehensively: it specifies result.market fields, result.analysis fields, result.evidence keying, the resolver contract fields (market_match_confidence, market_match_score, alternatives, suggestions), parent_event structure, news fallback fields, and safety statuses. Edge cases like closed markets and wide spreads are covered. Nothing important is left unexplained.

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

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

The input schema already has 100% coverage with detailed descriptions for all three parameters (market, depth, include_raw). The description adds minimal new parameter semantics beyond what the schema provides — it repeats that market can be a slug/URL/question text and gives fan-out examples, but does not clarify parameters like depth or include_raw further. 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 opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It names the exact input types (slug, URL, question text), lists classifiers, and gives fan-out examples. This clearly distinguishes it from siblings like polymarket_edges or deep_research.

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

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

The description explicitly states usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides guidance on when to inspect match confidence before trusting results. However, it does not name alternative tools or state 'do not use when...', so it lacks explicit exclusions.

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

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

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: it explains that company type pulls latest 10-K financials from SEC EDGAR/XBRL, handles off-calendar fiscal years, drug type pulls FAERS/FDA/trial counts, results are sorted by primary metric, and output includes paired data with pipeworx:// 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?

The description is dense but every sentence earns its place: trigger phrases are front-loaded, then each sentence covers a distinct aspect such as data sources, fiscal-year handling, sorting, output format, and efficiency. No filler or redundant schema repetition.

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

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

Despite having no output schema, the description fully explains what the tool returns (paired data + citation URIs), how results are sorted, what data sources are used, and how edge cases like off-calendar fiscal years are handled. This is sufficient for an agent to invoke the tool correctly without further lookups.

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

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

While the schema already covers both parameters at 100%, the description enriches them by defining what each type actually does: 'company' pulls fundamental financials, 'drug' pulls trial/adverse-event data. It also gives concrete examples ('AAPL','MSFT' / 'ozempic','mounjaro') and explains how values map to tickers/CIKs or drug names.

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: side-by-side comparison of 2-5 companies or drugs in one parallel call. It includes specific verbs like 'compare', 'rank', and 'head to head', and distinguishes itself from sequential single-entity lookups by describing its parallel nature and data sources.

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 to ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities, and provides example queries. However, it does not name a specific alternative tool for single-entity lookups or give explicit when-not-to-use cases, so the guidance is clear but slightly incomplete.

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 far beyond the annotations by disclosing account/paid-tier requirements, parallel decomposition across 5,439 tools, gap[] behavior ('never invented'), semantic excerpting of large records, hop fields and citation URIs, contradictions[] scanning for standard/thorough, and expected response times. This is rich behavioral context with no contradiction to the readOnlyHint/openWorldHint/idempotentHint annotations.

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

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

The description is densely informative and front-loaded with the critical account requirement, and each sentence provides new information. However, it is quite long (nearly 250 words) and some details (like exact timings) could be moved elsewhere, but it remains well-structured and not redundant.

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 (parallel routing, multiple depth modes, gaps[], contradictions[], citation formats, auth requirements) and lack of an output schema, the description thoroughly explains the return packet, behavioral limitations, timing, and alternative tools. No important aspect is left unexplained.

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 the schema already covers 100% of the parameters, the description adds substantial meaning: depth values map to facet counts (quick=3, standard=5, thorough=8), 'thorough' requires a paid plan, standard adds gap-recovery and contradictions scan, thorough adds a full iterative hop. It also clarifies that the question can be broad/multi-part, making the parameter usage far more actionable.

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

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

The description opens with 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources' in ONE call,' which clearly states the tool's verb (research) and resource (structured data). It explicitly distinguishes itself from open-web search and names the alternative ask_pipeworx for different use cases, making the 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 when-to-use guidance: 'Best for broad/multi-part questions over structured data,' plus concrete exclusions: 'For a single lookup use ask_pipeworx,' 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx,' and 'If you are not signed in, use ask_pipeworx instead.' This fully covers when to use the 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns top-N tools with names, descriptions, full input schemas, and curated examples, and states results are ready to call directly without a second schema lookup. This goes beyond annotations, though it omits details like rate limits or error handling.

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

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

The description is moderately long but front-loaded with the core purpose, followed by when-to-use, domain list, and return contract. Each sentence contributes value; the domain list is somewhat extensive but helps an agent gauge coverage. No obvious 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?

There is no output schema, so the description appropriately compensates by explaining exactly what is returned: top-N tools with names, descriptions, full input schemas, and curated examples, plus the note that results are directly callable. It also covers when to use it first. It lacks edge-case behavior (e.g., no results found) but is sufficiently complete for a read-only discovery tool with strong 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?

Parameter schema coverage is 100%, with query and its aliases (q, task, search, description) and limit (default 20, max 50) all documented in the schema. The description gives examples and reinforces that query is a natural language description, but it does not add new parameter meanings or usage constraints beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It enumerates supported domains (SEC filings, FDA drugs, FRED, etc.) and distinguishes itself from sibling tools like search or search_within by positioning it as a meta-tool for discovering which tools exist. The verb 'discover' is specific and the resource ('tools') is explicit.

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 to use it 'when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear usage context. It does not name specific alternative tools, but the 'call this first' guidance implies when not to use it (when you already know the exact 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?

The description discloses many behavioral traits beyond the annotations: it fans out across multiple data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields (CIK, company name, filings with URIs, fundamentals), and even notes the patents API sunset with soft-fail behavior and news fallback GDELT→GNews. These details add significant context and do not contradict the readOnly/idempotent 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?

Although the description is long, it is well-structured: it front-loads example queries for intent recognition, then defines the core behavior, and ends with a structured list of return fields and caveats. Each part adds value, but it is slightly more verbose than the minimum necessary, so it earns a 4 rather than a 5.

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

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

With no output schema present, the description fully compensates by enumerating all return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and providing edge-case behaviors (patents sunset, fallback news source, name limitation). This gives the agent complete context to correctly invoke the tool and interpret results.

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

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

The schema already has 100% coverage with detailed descriptions for both parameters: the enum 'type' and the 'value' field explaining ticker/CIK and name unsupported. The tool description essentially repeats the value format (e.g., 'Pass ticker "AAPL" or zero-padded CIK') without adding new meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call', using a specific verb ('profile') and resource ('US public company'). It also distinguishes itself from related tools by explicitly warning against chaining single-pack SEC/XBRL/news lookups and by including example queries that clarify its intent.

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

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

It provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies a when-not and alternative: 'names not supported (use resolve_entity first if you only have a name).' This is clear and actionable.

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

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

Beyond annotations (readOnly, idempotent), the description adds concrete behavioral details: strips boilerplate/navigation, returns up to 20,000 characters per page, and accepts both single URL and array inputs. It also notes the API key fallback behavior. No contradictions with annotations.

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

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

Two sentences, front-loaded with the primary action, and every clause contributes value. No filler or repetition.

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

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

For a simple read-only extraction tool with no output schema, the description covers input formats, processing behavior, output limits, and intended use case. This is complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, and the description adds no meaningful parameter-specific information beyond what is already in the schema. The description mentions accepting a string or array, but this is already documented in the schema property description and examples.

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

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

The description uses a specific verb and resource: 'Extract clean article text from one or more URLs via Tavily.' It clearly distinguishes from sibling tools like search and search_within by focusing on content extraction rather than search results.

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 with 'Ideal for feeding source pages into an LLM,' which signals when to use. However, it does not explicitly mention when not to use or name alternative tools, so it stops short of full 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 disclose destructiveHint=true and readOnlyHint=false, so the description doesn't need to repeat mutation risk. It adds minor context by mentioning 'sensitive data' and 'previously stored memory', but no additional behavior such as missing-key handling or persistence effects is described.

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, immediately front-loaded with the action, and every word adds value. It is well-structured and free of filler.

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

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

For a simple one-parameter tool with no output schema, the combination of annotations, schema, and description is complete. It explains the operation, when to use it, and its relationship to sibling tools, leaving no significant gaps.

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

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

Schema coverage is 100% and the description's 'by key' echoes the existing parameter description. No new meaning is added beyond what the input schema already states, so a baseline score of 3 is appropriate.

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

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

The description starts with a specific verb ('Delete') and a clear resource ('a previously stored memory by key'), distinguishing it from sibling tools like remember and recall. It unambiguously states what the tool does.

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 ('context is stale, the task is done, or you want to clear sensitive data') and mentions pairing with remember and recall. Lacks an explicit when-not-to-use statement, but the guidance is otherwise 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 readOnly, idempotent, and non-destructive behavior. The description adds the fetch-extract-emit process and clarifies the output is a single text blob ready for site-root/llms.txt, which goes beyond annotation-provided safety and adds useful behavioral context.

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

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

The description is concise at three sentences, front-loaded with purpose, then process, then use cases. Every sentence contributes value with no filler or 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 simple tool, full schema coverage, and strong annotations, the description covers purpose, process, output format, and practical use cases. It is complete for an agent to select and invoke correctly without requiring additional 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 input schema covers 100% of parameters with descriptive comments for url and max_links. The description adds little beyond the schema, but the schema already provides full semantics, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for any URL, with a specific verb and resource. It details the process (fetches, extracts title/description/key links, emits standard markdown) and distinguishes it from sibling tools by focusing on the llms.txt output.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for your own project, and auditing a competitor. It gives clear context for when to use the tool, though it doesn't explicitly exclude alternatives or name them.

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, so the safety profile is covered. The description adds useful behavioral context by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and the default scope of 'active' subscriptions. No contradiction 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, front-loaded with the purpose and return fields, followed by usage guidance. Every sentence earns its place with no redundancy or fluff.

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

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

Given the tool has only one optional parameter, rich annotations, and no output schema, the description compensates by listing the return fields and providing usage context. It is fully adequate for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% coverage for the single parameter include_inactive, with a clear description ('Include cancelled subscriptions in the response (default false)'). The tool description does not add further parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb (list), resource (subscriptions), and scope (caller's active). It also enumerates the returned fields, and the context of sibling tools (subscribe, unsubscribe) makes its purpose distinct.

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

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

The description explicitly tells when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear use cases and implicitly contrasts with the sibling subscribe and unsubscribe 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 are all false (neutral), so the description carries the burden. It adds valuable context: rate-limited to 5 per identifier per day, free (doesn't count against tool-call quota), team reads digests daily, and signal affects roadmap. Also clarifies content boundaries (don't paste end-user prompt). 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: purpose first, then usage conditions, exclusions, content guidance, and rate limits. Every sentence adds useful information, though some trimming could improve scannability 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?

For a simple feedback tool with no output schema, the description covers purpose, scope, when/when-not, content guidelines, rate limits, and quota behavior. It is fully complete for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the meaning of 'type' (bug, feature, data_gap, praise) and adds advice about message content (don't paste end-user prompt), but doesn't significantly extend the schema's parameter descriptions.

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

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

The description clearly states the purpose: tell the Pipeworx team when something is broken, missing, or needs to exist. It specifies the verb ('tell') and resource ('Pipeworx team'), and distinguishes itself from the sibling tools by being the feedback channel rather than a research/search 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 defines when to use (bug, feature/data_gap, praise) and when NOT to use (if the tool came from a different MCP server, file with that server instead). Also provides a decision rule for uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists').

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

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

Annotations already indicate read-only and idempotent behavior, but the description adds significant context: the data source (CF analytics-engine), no PII, the return shape (pack, tool, count), and caching windows. This goes well beyond the annotations and helps set expectations.

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

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

The description is front-loaded with a clear purpose statement, then provides return details, numbered use cases, and data characteristics. Every sentence contributes useful information, and the structure makes it easy to scan.

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

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

For a simple read-only tool with one optional parameter and rich annotations, the description covering the output shape, source, privacy, and caching is complete. Even without an output schema, the agent knows what to expect from 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?

The schema fully describes the 'window' parameter with an enum and meaning, so the baseline is 3. The description only mentions the window in passing and adds a related caching detail, which is marginal extra 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 function: it returns top tools, top packs, and total call volume based on other AI agents' calls to Pipeworx. The verb 'Returns' and explicit output list distinguish it from siblings like discover_tools, emphasizing its self-aggregating nature.

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 ('Useful for...') that tell the agent when to use it, such as discovering hot data sources and confirming canonical tools. However, it does not name alternatives or explicitly state when not to use it, leaving exclusions implicit.

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, and the description adds rich behavioral context beyond that: the 3pp deviation threshold, placeholder filtering logic (PARTITION FILTER), fill check against live CLOB depth, and the meaning of skipped_low_similarity. Also discloses that a signal may be theoretical only ('overround exists only at last-trade, not in the book'). 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 and dense, but organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and uses bullet-like clarity within prose. Some redundancy exists (e.g., restating that partition_check sums to ~1), but given the tool's complexity, the length is mostly earned. Could be tightened 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?

Without an output schema, the description directly explains the response structure (opportunities[], partition_check, fill_check details) and covers edge cases (skipped_low_similarity, placeholders_filtered, thin_legs). This is a complete picture for the agent to know what the tool returns and how to interpret it, including the crucial warning about realizable edge.

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

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

Schema description coverage is 100%, but the description still adds significant meaning by providing example slugs ('fed-decision-may-2026'), clarifying that full URLs are accepted, and explaining the behavioral difference between `event` and `topic` modes beyond their schema descriptions. The description gives concrete use cases and what to expect from each parameter.

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 ('Find arbitrage opportunities') with a clear resource ('Polymarket') and method ('monotonicity violations + partition-sum checks'). It distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection, not just edges or 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?

Explicitly explains when to use each mode: NO args for trending_scan, `event` for a specific market, `topic` for cross-event scanning. Also mentions alternative tools ('For custom sizing use polymarket_fill_risk') and warns when a signal should not be traded, e.g., 'realizable_edge_pp ≤ 0... do not trade it'.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description goes far beyond by disclosing the internal model families, response structure, caching behavior ('Cached 1h at the KV level keyed on all knobs'), the special partition Kelly behavior, and the 24h-move warning. It also explains why segments may be empty via _diagnostics. This is a model of behavioral 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 very long but every sentence adds value, and it's front-loaded with the purpose. It uses all-caps section markers and parentheses to organize a dense amount of information. Given the tool's complexity (9 parameters, three model families, response details), the length is justifiable, though it could be broken into more readable 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?

Despite having no output schema, the description thoroughly covers the response structure (by_segment, fed_candidates/fed_note, _diagnostics), explains what each opportunity carries, and even tells callers why a segment might be empty. Combined with detailed parameter semantics and annotations, this is a complete picture for an agent to use the tool effectively.

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

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

The input schema already covers all 9 parameters with descriptions (100% coverage), so the baseline is 3. The description significantly enhances parameter understanding by explaining how knobs interact (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and clarifying the special case of min_partition_leg_kelly with partition arbs. This goes well 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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case ('what should I bet on today'). It doesn't explicitly distinguish itself from sibling tools like polymarket_arbitrage, but the focus on edge opportunities and the detailed model families make the purpose unmistakable.

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

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

The description gives a clear usage context ('agents discover opportunities without paging hundreds of markets'), explains tradeable-edge knobs and when to adjust them (e.g., 'Set to 2 to require tight books'), and notes exclusions (Fed bets excluded from ranking due to unreliable signal). It doesn't name alternative tools directly, but the guidance is rich enough to know 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals detailed behavior: snapshots are written on cache-miss, gaps in snapshot_dates mean no scan occurred, history is bounded by a 60-day TTL, and decay is computed from daily closes, not intraday. This is substantial context not available in 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 well-structured with clear sections (opening purpose, Args, RESPONSE, LIMITS). It is detailed but every sentence contributes crucial information about data provenance, return fields, and pitfalls. The length is justified by the complexity, and it is front-loaded with the core question it answers.

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?

There is no output schema, so the description must explain return values. It does so thoroughly, enumerating tracked[], expired[], and snapshot_dates[] with field-level detail (edge_pp_net time-series, trend, decay, lifespan). It also covers limitations like TTL and snapshot gaps, making it sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 100% and the schema already explains both parameters (days as lookback with clamp, window as the snapshot family). The description restates these and adds minimal new meaning (e.g., 'max 30' is already implied by 'clamp 2-30'). Thus the description adds little beyond what the schema provides.

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

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

The description opens with a specific verb phrase 'Edge persistence and decay telemetry' and directly states the tool's purpose: answering 'how long has this edge existed and is it shrinking?'. This clearly distinguishes it from the sibling tool polymarket_edges by focusing on temporal persistence 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?

The description conveys a clear use case: when to care about edge age ('a fresh wide edge and a 3-week-old wide edge are different trades'). It also gives LIMITS that help set expectations, but it does not explicitly name alternatives like polymarket_edges for when only current edges are needed.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond by disclosing mode-specific behavior, return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), the interpretation of size_usd in each mode, and the risk of partial basket fills. No contradiction with annotations exists; the description adds rich 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 dense and long, but every sentence provides necessary detail for a dual-mode tool with critical risk warnings. It is front-loaded with the core purpose and then structured by mode, return values, and usage guidance. The length is justified by the complexity; still, some redundancy (e.g., repeating 'top-of-book vs VWAP') could be trimmed.

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?

There is no output schema, so the description carries the full burden of explaining return values, which it does thoroughly for both single-market and basket modes. It covers required inputs, optional parameters, defaults, edge cases (thin_legs, forced_directional_risk), and actionable usage context. For a complex tool with zero output schema, this is complete.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema by explaining how 'market' and 'event' select modes, how 'side' defaults differ by mode, and how 'size_usd' is interpreted (max spend vs target proceeds vs settlement notional). It also mentions the clamp range, which is not in the schema, making parameter usage unambiguous.

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 ('checks') and resource ('realizable-vs-theoretical edge against live CLOB order-book depth'), and clearly differentiates between single-market and basket modes. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal generation or edge calculation.

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

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

The description explicitly states when to use the tool ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains the consequences of not using it (theoretical overround on thin books is not capturable, partial fills create unhedged directional risk). It also names no alternative tools, but the context is clear and actionable.

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 far beyond the annotations by detailing internal behaviors: conditions for compatibility_warning, temporal_alignment semantics, and the meaning of skipped_cross_type/subtype counters. It also discloses that most pre-mapped topics currently return warnings, which is important behavioral nuance. No contradiction with annotations exists.

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 (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence carries information essential for a tool with no output schema. It is front-loaded with the core purpose and uses typographic cues (bolding, parentheses) to aid scanning, though slightly verbose in the safety-fields explanation.

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

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

For a tool with no output schema, the description does an excellent job of covering the expected response fields (venue prices, spread, compatibility_warning, temporal_alignment, skipped counters) and their interpretation. It also addresses edge cases (non-equivalent bet shapes, temporal misalignment) that the agent would otherwise be blind to, making the description complete 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?

Although the input schema already covers the parameters (100% coverage), the description adds critical semantic context: it explains that 'topic' auto-fetches matching events from each venue and that the explicit parameters override the topic-mapped side. This clarifies the relationship between parameters and their runtime effect, adding value beyond the schema.

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

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

The description opens with a specific, action-oriented statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools by emphasizing the two-venue comparison and the compatibility checks (e.g., 'when they aren't the tool says so'), which sets it apart from related tools like polymarket_arbitrage.

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

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

The description provides clear guidance on when to use each mode: 'TWO MODES: (1) topic... (2) explicit kalshi_event_ticker + polymarket_event_slug.' It also warns about the reliability of pre-mapped topics ('pre-mapped ≠ tradeable'), which helps the agent set expectations. However, it does not explicitly name alternative tools or state 'use this instead of X,' so it falls short of the highest bar.

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 readOnly/I idempotent annotations, it discloses that memory is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID), which is important for data isolation. It also describes the conditional list behavior when the key is omitted, adding value beyond annotations.

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

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

The description is concise, front-loaded with the primary action, and every sentence earns its place. It covers retrieval, listing, usage context, scoping, and related tools in just two sentences 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?

Given the tool's simplicity, the description covers purpose, usage, scoping, and relationships. It lacks an explicit return format for missing keys, but the annotations and clear examples make it complete enough for effective selection and invocation.

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

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

The input schema already fully describes the sole parameter key, including the 'omit to list all keys' behavior. The description repeats this and adds examples of key content, but does not introduce new syntax or constraints, so baseline 3 applies.

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

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

Clearly states it retrieves a previously saved value or lists all keys when the key argument is omitted. The verb 'retrieve/list' with the resource 'memory key' is specific, and it distinguishes from siblings by explicitly pairing with remember 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 usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the complementary tools remember and forget, giving clear alternatives and implicit when-not (to save, use remember; to delete, use 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?

Beyond annotations (readOnlyHint, idempotentHint), the description discloses the mark_read side effect (flipping read state) and explains what each event carries (source, citation_uri, raw payload). It also notes the same feed is available via a public URL. This adds substantial context without contradicting annotations.

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

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

The description is compact and front-loaded with the primary purpose. Each sentence provides distinct value: what it does, what it returns, how to filter, mark_read behavior, and alternative access. No fluff or 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 5 optional parameters, no output schema, and rich annotations, the description covers the return payload, filtering, mark_read, and polling/alternative access. It lacks explicit pagination or error-handling notes, but these are minor gaps for a read-only polling tool.

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

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

Schema descriptions cover all 5 parameters, so baseline is 3. The description adds a concrete type example ('sec_8k') and clarifies the behavioral effect of mark_read, but most parameter meaning is already captured in the schema. It does not fully compensate for the lack of enums or detailed value formatting.

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

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

The description opens with 'Pull fired events from your subscription feed', which names a specific verb and resource. It clearly distinguishes this from sibling tools like 'recent_changes' by focusing on alerts/subscription events.

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

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

The description gives practical guidance: filtering by type/since, using mark_read to control subsequent reads, and polling. It also mentions an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly contrast with sibling tools like list_subscriptions or recent_changes.

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 reveals significant behavioral details beyond the annotations: it fans out to SEC EDGAR, GDELT→GNews (with fallback logic), and USPTO (with a noted API sunset causing soft-fail). This is valuable operational context that annotations do not 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?

Despite its length, the description is dense and well-structured: it opens with query examples, defines the core behavior, explains internal source fan-out and fallbacks, details the `since` parameter, and closes with a sibling contrast. Every sentence contributes necessary 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?

The description covers the return format (changes[], total_changes, citation URIs), source behavior, parameter formats, and alternative tool usage. Given the tool's complexity and lack of an output schema, this is a complete and self-sufficient description.

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 concrete examples for `since` ('7d', '30d', '3m', '1y') and a usage recommendation, which slightly enhances understanding beyond the schema's minimal definition.

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

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

The description clearly states the tool is a 'change feed for a company' and provides multiple example query forms ('What's new with X', 'updates on Acme') that make its purpose immediately recognizable. It also explicitly contrasts with entity_profile, distinguishing it 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 gives explicit when-to-use guidance via the query examples and directly names an alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This covers both when to use and 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 show this is a write (readOnly=false), idempotent, non-destructive operation. The description adds useful context: persistence depends on auth (authenticated = persistent; anonymous = 24h) and values are scoped by identifier. It does not explicitly state whether re-saving the same key overwrites the existing value, but overall it exceeds the annotation baseline.

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 four sentences, front-loaded with the main action, and each sentence contributes: what it does, when to use it, storage format/scope, persistence, and related tools. No unnecessary filler.

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

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

For a simple 2-parameter tool with no output schema, this description is complete: it explains the tool's behavior, gives use cases, describes memory scope and retention, and points to related tools (recall, forget). No meaningful gaps remain.

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

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

The schema already fully documents both parameters (key and value) with examples (100% coverage). The description only reinforces that this is a key-value pair, adding no new semantic detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with 'Save data the agent will need to reuse later' and specifies scope across conversation/sessions. It clearly distinguishes from siblings recall (retrieve) and forget (delete) by naming them, making the tool's 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?

Explicitly states 'Use when you discover something worth carrying forward' with concrete examples, and tells the agent to pair with recall/forget for later retrieval/deletion. It lacks explicit when-not or exclusion cases, but the guidance is clear.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, so the description does not need to repeat safety traits. It adds valuable behavioral context: the internal cascade across multiple lookup endpoints, the specific data sources (SEC EDGAR, RxNorm), and the citation URIs returned.

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 example phrases, a 'SUPPORTED TYPES' section, and clear explanations of outputs. It is slightly longer than minimal, but every sentence adds necessary information, making the length justified.

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

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

With no output schema, the description compensates by detailing return values for both types and the internal lookup cascade. It does not cover failure modes or ambiguous input handling, but the provided information is sufficient for most usage scenarios.

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 the schema covers all parameters, the description goes beyond it with concrete examples (e.g., 'AAPL', '0000320193', 'ozempic') and clarifies auto-disambiguation behavior. This extra guidance significantly improves the agent's ability to populate the value parameter correctly for different types.

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 verb and resource: it resolves a user-spoken name to the canonical identifier needed by other tools. Specific examples of user queries and the two supported types (company, drug) with their returned identifiers make the 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 phrase 'Use FIRST whenever you have a name but need an ID' provides explicit usage context, and the example queries reinforce when to invoke it. However, it does not explicitly state when not to use it or mention alternative tools, leaving a small gap.

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, and non-destructive behavior. The description adds valuable context beyond that: it reveals the tool is a meta-probe that internally calls ai_visibility_check multiple times, and it discloses the return contents (ranked list with score, confidence, signal density). This goes beyond what annotations provide.

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

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

Two sentences, front-loaded with the core purpose ('Compare AI visibility across multiple entities side-by-side'), followed by mechanism, use case, and return format. Every sentence earns its place 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?

Given the tool's moderate complexity (4 parameters, no output schema) and rich annotations, the description covers the essential behavior, return value shape, and example use case. It slightly lacks explicit mention of how models/_apiKey affect probing behavior, but that is covered by the schema. Overall, it is adequately 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 description coverage is 100%, so the baseline is 3. The description does not elaborate on parameters, but the schema already contains detailed descriptions for entities, models, _apiKey, and context, including semantics like 'First entry treated as the subject'. Thus the description adds no additional parameter 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 states a specific verb ('Compare'), a resource ('AI visibility across multiple entities'), and the mechanism ('Probes each entity with ai_visibility_check, ranks by score'). It clearly distinguishes from siblings like ai_visibility_check (single-entity) and compare_entities (generic) by focusing on competitive AI-marketing visibility.

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 a clear use case: 'competitive AI-marketing audits' with an example question. It implies this is the batch/competitor-oriented counterpart to ai_visibility_check, but does not explicitly name alternatives or state when not to use it. Thus it has clear context but no exclusions.

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

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

Beyond the read-only and idempotent annotations, the description discloses critical behavioral details: it fans out to two external services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and the sources_failed field reports timeouts. This is comprehensive transparency that aids the agent in setting expectations.

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

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

The description is a single, dense paragraph that front-loads the core purpose and provides all necessary information in a structured flow: purpose, usage, return value, failure behavior, and ecosystem limitations. Every sentence adds value, with no redundant content.

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

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

Given the complexity of the tool (multi-source aggregation) and the absence of an output schema, the description fully enumerates the return fields, failure behavior, and timing expectations. This is more than sufficient for an agent to understand what the tool does and what to expect from its results.

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

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

The input schema already provides 100% coverage for both parameters, including descriptions for 'package' and 'version'. The description adds minimal additional parameter context (e.g., NPM ecosystem only, scoped packages accepted) which mostly mirrors the schema, so it does not significantly elevate the baseline score.

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

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

The description clearly states the tool's purpose as a composite 'should I add this npm package' check, detailing the specific data sources and the types of questions it answers. This distinguishes it from sibling tools like deep_research or validate_claim by focusing on npm dependency evaluation.

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

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

Explicitly states when to use the tool ('Use whenever an agent asks...') and provides clear exclusions for non-NPM ecosystems, directing to deps.dev:version directly. This gives strong guidance on when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds meaningful behavioral context: that it returns a synthesized answer and a ranked list with relevance scores, which is beyond the schema. It doesn't discuss rate limits or errors, but this is acceptable given annotation coverage.

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

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

The description is two sentences plus an example, with no wasted words. It front-loads the purpose, then adds usage guidance and a concrete example, all of which earn their 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?

An output schema exists, so the description needn't fully explain return values, yet it still conveys the key output structure (synthesized answer plus ranked sources). Combined with the schema, the overall package is complete for a search tool of this complexity, though it could mention which sibling scenarios it is not suited for.

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

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

Schema description coverage is 100%, with each of the six parameters described, including enums for topic and search_depth. The description provides an example but no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description states a specific verb-resource pair ('AI/LLM-optimized web search') and clearly defines the output: a synthesized natural-language answer plus a ranked list of sourced results with title, URL, snippet, and relevance score. It explicitly distinguishes the tool from scraping a generic search engine, which aligns with its sibling context.

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

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

The description provides explicit guidance to prefer this tool over scraping a generic search engine when grounded, citable web context is needed. It does not contrast with sibling tools like deep_research or search_within, but the alternative it names is actionable and relevant.

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 several behavioral traits beyond the annotations: it returns 'character offsets and similarity scores', uses 'BGE-base-en embeddings + cosine over 500-char overlapping windows', and has a '200K chars cap (longer inputs are truncated and flagged)'. These details inform the agent about output format, performance characteristics, and failure modes—valuable context that annotations don't provide. No contradiction with the readOnly/idempotent hints.

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

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

The description is dense but well-structured, with clear front-loading of purpose and usage. Each sentence contributes value: purpose, use case, companion tool, technical details, and limits. It's slightly longer than strictly necessary, but no sentence is wasteful. The structure aids readability and 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?

For a tool with no output schema, the description explains what the agent receives (top-N passages with character offsets and similarity scores) and the operational context (when to use, truncation behavior). It covers the main use case, integration with a sibling tool, and technical constraints. The description is sufficiently complete for an agent to invoke the tool correctly.

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

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

The schema already documents all 3 parameters with descriptions (100% coverage), so baseline is 3. The tool description adds illustrative examples for the 'text' parameter (e.g., 'SEC 10-K body, article, long tool result') and clarifies the 'query' parameter with natural-language examples. This goes beyond the schema's generic descriptions, enriching parameter understanding without duplicating 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 performs semantic search inside a fetched record, with a specific verb ('search') and resource ('record/text'). It distinguishes itself from siblings by explicitly noting 'INSIDE a fetched record' and referencing ask_pipeworx_grounded as a companion tool. The purpose is unambiguous and differentiates from broader search 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 states when to use this tool: 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context, returns only relevant passages). It also provides an explicit alternative/companion workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear usage context and exclusion.

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 (readOnly=false, idempotent=true, etc.), the description adds significant behavioral detail: the auth requirement and persistence limitation, phone verification and 10/day SMS cap, and the feed delivery mechanism via recent_alerts or a registry URL. This enriches the agent's understanding beyond what annotations alone convey.

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-organized, front-loading purpose and then covering auth, types, and delivery. Every sentence carries necessary information, and the length is justified by the tool's complexity. It avoids verbosity and remains scannable despite the many details.

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

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

Given the complexity (multiple subscription types, nested delivery options, no output schema), the description covers the core aspects: subscriptions, auth, types, and delivery. However, it omits the webhook delivery channel from the main prose and misses two subscription types (patent_grant, clinical_trial) that are only in the schema. Still, the schema fills these gaps, so the description is nearly 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?

The input schema already provides 100% coverage of all parameters with detailed descriptions, including the nested delivery object. The description's main text adds readability with concrete examples (e.g., items:["5.02"] = officer change) but does not fundamentally extend the schema's meaning. Since schema coverage is high, a baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from siblings like list_subscriptions and unsubscribe, and even states it returns the new subscription id. This leaves no ambiguity about the tool's function.

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

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

The description provides clear context for when to use the tool: it requires a Pipeworx OAuth account, notes that anonymous/BYO cannot persist, and explains delivery channels including the always-on feed and optional email/SMS. However, it does not explicitly name alternatives or state when not to use it (e.g., 'use list_subscriptions to view existing'), though this can be inferred from sibling names.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds substantial behavioral context: it returns example questions (not answers), draws from a 'live catalog of thousands of tools', and can be scoped by topic. This goes beyond the annotations by explaining the output's nature and dynamic source, with 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 front-loaded with natural user queries, followed by a precise statement of purpose, output composition, and usage instructions. Although it is relatively long, every sentence contributes essential context for an onboarding tool. The structure flows logically from what the tool does to how to call it, making it efficient for an agent to parse.

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

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

The description covers all necessary aspects: purpose, input options, output outline (category-bucketed questions with exact tool + argument shape), and its role in learning meta-tools. Without an output schema, this description sufficiently explains what the agent will receive and how to use the results. It is complete for an onboarding tool of this complexity.

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

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

The input schema already fully describes the optional `topic` parameter, including allowed values and the behavior when omitted. The description merely repeats examples like 'finance', 'pharma', 'betting' and the 'no arguments' case, adding no new constraints, semantics, or interaction details beyond what the schema provides. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly identifies the tool as the onboarding entry point for connected agents, with a specific function: 'Returns category-bucketed example questions ... each with the exact tool + argument shape that answers it.' It also distinguishes itself from siblings by emphasizing that it is the FIRST tool to use when you don't know what Pipeworx can do, and it exists to teach how to call meta-tools like ask_pipeworx, entity_profile, and compare_entities.

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

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

Explicit guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also describes two invocation modes (no arguments for full spread, or topic for focus) and provides examples of valid topic values. This clearly informs when and how to use the tool, and indirectly implies it's not needed when you already know what to ask.

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 the annotations: ownership enforcement, deactivation instead of deletion, and preservation of historical events via recent_alerts. This complements the annotations (e.g., destructiveHint=false) by explaining the non-destructive nature in concrete terms. No contradiction with annotations.

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

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

The description is concise and front-loaded: two sentences that state the action, key constraints, and side-effect behavior. Every sentence adds value, with no filler or repetition of schema details.

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

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

For a simple one-parameter tool, the description covers the essential aspects: purpose, ownership, and the non-destructive deactivation behavior. It could mention error cases (e.g., nonexistent id) or reversibility, but these are not critical for basic usage. The lack of an output schema is adequately compensated by the behavioral explanation.

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 the parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description's 'by id' adds nothing beyond this. The baseline of 3 is appropriate since the schema already fully documents the parameter.

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: 'Cancel a subscription by id.' This uses a specific verb and resource, directly distinguishing it from siblings like 'subscribe' and 'list_subscriptions.' The purpose is unambiguous.

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

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

The description provides clear context for when to use the tool—to cancel a subscription—and explicitly notes a constraint: 'you can only cancel your own subscriptions.' This effectively tells the agent when not to use it (for others' subscriptions), though it doesn't name alternative tools explicitly. The deactivation note also clarifies the side-effect context.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses rich behavioral details: the dual-path routing (SEC EDGAR/XBRL vs. grounded pipeline), exact percent-delta math, tolerance cap, verdict types, attribution, and that it replaces multiple sequential calls. This is substantial added 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 well-structured and efficient. It opens with trigger phrases, states the core action, outlines routing logic, describes return values, and ends with a value-add comparison. Every sentence contributes unique information without redundancy, striking a good balance between detail and brevity.

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 two parameters (one required), no output schema, and strong annotations, the description fully compensates by explaining what the tool returns (verdict, actual value, citation, reasoning), the tolerance behavior, and the routing logic. It is complete enough for an agent to correctly invoke and interpret 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?

The schema covers both parameters well (100% coverage), so the baseline is 3. The description adds extra value by explaining the tolerance_pct overrides the claim's implied tolerance and its default cap (5%, range 0.5-50), which is not fully captured in the schema. It enhances understanding of parameter behavior.

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 natural-language claim verification against authoritative sources, with explicit trigger phrases and a specific verb ('verify'). It distinguishes itself from sibling tools like ask_pipeworx or deep_research by focusing on confirming/refuting factual claims, 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?

It provides clear usage context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates behavior for company-financial vs. other claims. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of full 5.

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