Activecampaign

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds value by explaining the probing behavior, per-model and combined return structure, and pricing (free vs BYO key). 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?

Two sentences with no waste. First sentence covers purpose and return value. Second sentence adds model selection, pricing, and use cases. Front-loaded and efficient.

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

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

Description covers purpose, parameters, model selection, API key handling, and use cases. Though no output schema exists, the description adequately describes return structure. Complete enough for agent invocation.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds meaning by explaining entity (with examples), models (supported values), _apiKey (BYO key and direct billing), and context (disambiguation use).

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

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

The description clearly states the tool probes LLMs for entity knowledge and scores visibility (0-100) per model, distinguishing it from siblings like scan_competitor_ai_presence by focusing on visibility scoring and multi-model support.

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 mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to pass _apiKey for Anthropic. However, it does not explicitly state when not to use or compare to specific siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this by describing it as 'one fast call' and 'works on every tier'. It adds behavioral context about routing behavior and citation format (stable pipeworx:// URIs), which goes beyond annotations. Could add more about rate limits or response latency, but the annotation coverage is strong.

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 information-dense and front-loaded with the headline 'PREFER OVER WEB SEARCH' and the primary use case. The examples are useful and concrete. It's slightly long (multiple sentences covering scenarios), but every sentence earns its place — routing scope, citation format, examples, and tier escalation guidance all add distinct value.

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

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

For a read-only, open-world router tool with rich annotations and a fully documented schema, the description is complete. It covers purpose, scope, when to use, when to step up to alternatives, examples, and behavioral guarantees. No output schema exists, but the description explains the expected return (structured answer with stable pipeworx:// citation URIs), which adequately compensates.

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 the `question` parameter and its five aliases (query, q, prompt, text, input) fully documented in the schema. The description adds value by indicating natural-language questions are acceptable and showing example questions, but doesn't add substantial semantics 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 uses specific verbs ('asks', 'routes') and clearly identifies the resource (a router to 5,347 tools across 1,393 verified sources). It thoroughly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as explicit alternatives, and provides concrete examples of when to prefer it.

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 'PREFER OVER WEB SEARCH' and provides clear when-to-use directives with query-phrase patterns ('what is', 'look up', 'find') and concrete examples. It also names sibling tools for step-up use cases (grounded, deep_research) and defines what it's NOT for (breaking news 'what's the world saying' routes to news feeds).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is well established. The description adds meaningful behavioral context: it clarifies this is 'a full working router' not a stub/fallback, that no candidate is currently active (matching stable exactly as of 2026-07-26), and that results are compared against the stable router for merge decisions. This temporal/testing context is genuine added 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 a single focused paragraph that front-loads the essential identity (beta of ask_pipeworx) before details. It's appropriately sized for a tool with this testing nuance — longer than a one-liner but every sentence carries information about routing, current status, and merge behavior. Slightly verbose in the final sentence but not bloated.

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 (universal router with 5,347 tools, testing context, experimental status), the description covers the key operational facts: current parity with stable, why it exists, and its fallback behavior. No output schema exists, so return-value explanation is absent but the stable sibling presumably documents the response shape. It adequately covers what an agent needs to safely and correctly select and use this beta variant.

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% — every parameter is documented in the schema (q/text/input/query/prompt aliases for question). The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 is appropriate. The schema itself is clear about the aliases, so no compensation is needed from the description.

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

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

The description clearly states this is a beta variant of ask_pipeworx — a universal router with 5,347 tools and identical arguments/response shape. It distinguishes from the stable sibling by explaining it carries candidate routing improvements when under test. However, it doesn't fully establish the tool's core function from scratch (what 'routing' means here), relying heavily on referencing the sibling identity.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts against the stable router used for comparison/merge decisions. It names the sibling ask_pipeworx as the functional equivalent. However, it doesn't give when-NOT-to-use guidance or alternatives for cases where grounding matters (the ask_pipeworx_grounded sibling exists but isn't referenced).

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds substantial operational detail: the full success response shape ({answer, evidence (verbatim quote), confidence, source, fetched_at, refusal_reason:null}), the explicit refusal behavior with 5 enumerated refusal_reason values, and the cost difference. This is exceptionally transparent about behavior the annotations cannot 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 information-dense but well-organized: it front-loads the core concept, then details the mechanism, then return shape, then use cases, then cost tradeoff. Every sentence earns its place — there's no filler or repetition of annotation content. The flow from what→how→when→cost is logical and complete.

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 specifies the return contract (success fields and all refusal reasons). The tool is complex (routing across 5,347 tools, 1393 sources) but the description covers all operational aspects: how it routes, what it guarantees (verbatim evidence), when it refuses, and cost implications. Nothing essential is left unsaid for an agent to select and use it correctly.

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

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

Schema description coverage is 100% — all 6 parameters (question plus 5 aliases) are documented in the schema with descriptions. The description does not add parameter-level detail beyond noting 'fills arguments' internally, but it doesn't need to since the schema already fully covers all parameters. The one useful addition (query semantics around natural language question) is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads' with the exact mode name (grounded). It distinguishes itself from its sibling ask_pipeworx by explaining the key differentiator (evidence extraction, refusal behavior). The purpose is unambiguous and distinct from the 35 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 explicitly states when to use it ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'), gives concrete use cases (financial verdicts, legal claims, medical lookups, public statements), and explicitly says to prefer ask_pipeworx for casual lookups. It also names the alternative (ask_pipeworx) and the tradeoff (one extra LLM call). This is exemplary usage guidance.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive detail: fan-out logic, response structure, resolver contract, safety/blocking of low-confidence matches, closed market handling, wide spread warnings, and resolution-rule risk. No contradictions with annotations.

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

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

The description is very long and covers many aspects in detail. It front-loads purpose but becomes verbose with extensive lists (classifiers, fan-out examples, response shapes). Some redundancy could be trimmed for better conciseness.

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

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

Given no output schema and high complexity (3 params, many response fields, edge cases), the description is thoroughly complete. It documents response shapes, resolver contract, parent event extraction, news fallback behavior, safety mechanisms, and resolution-rule risk. Covers all expected 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?

Schema coverage is 100% with descriptions for all 3 parameters. The description adds context (e.g., 'include_raw' response size implications) but does not substantially exceed schema information. 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' with specific input types and classifiers. It distinguishes itself from sibling Polymarket tools (e.g., polymarket_edges, polymarket_arbitrage) by being a comprehensive research aggregator.

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 examples: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' While no direct 'when not to use' statement, the context and sibling tools imply it's for initial research, not deeper edge analysis.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds significant context: SEC EDGAR/XBRL for companies, FAERS for drugs, handles off-calendar fiscal years, sorted results, citation URIs. No contradictions.

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

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

Slightly long but every sentence adds value. Front-loads purpose with examples. Could be tightened but remains effective.

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

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

No output schema, so description explains return (paired data + citation URIs). Covers edge cases (off-calendar fiscal years). For 2-param tool, description is fully 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 100%, but description enhances both parameters: explains 'type' enum with data source (10-K vs FAERS), and 'values' with examples (tickers/CIKs for company, drug names) and constraints (2-5). Adds meaning beyond schema.

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

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

Description clearly states the tool does side-by-side comparison of 2-5 companies or drugs in one parallel call. It specifies types (company or drug), data sources, and sorting. It distinguishes from siblings by explicitly preferring over sequential single-pack lookups.

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

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

Provides explicit when-to-use examples like 'X vs Y', 'which is bigger', 'rank these companies'. Recommends always using over sequential lookups. Does not state when not to use, but context is clear.

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

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

Despite annotations already declaring readOnlyHint=true and openWorldHint=true, the description adds substantial behavioral context: account requirement (free vs paid tiers), expected latency (15-60s, up to ~90s), gap[]/contradictions[] return behavior, hop fields, semantic excerpting (not head-truncated), PARALLEL tool routing, and the never-invent-findings guarantee. This goes far beyond what annotations 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?

Very information-dense but loses points for length and some redundancy. Key distinctions (parallel routing, gap[], not open-web) are front-loaded in the first two sentences, which is good. However, several clauses repeat or could be tightened (e.g., 'decomposes your question into focused facets' and 'routes each to the right one of 5,347 tools' both appear; depth tier details are enumerated twice in description and schema). Still, nearly every sentence earns its place given the tool's complexity.

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

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

For a complex tool with 2 enums, no output schema, and rich annotations, this description is remarkably complete. It explains the account/auth gate, covers return structure (findings packet: evidence + confidence + source + fetched_at + citation), the gaps[] and contradictions[] behavior, the excerpting strategy, latency expectations, and the second-hop iteration mechanics. Given no output schema, the description carries the full burden of explaining the response format and does so thoroughly.

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 schema already fully documents both parameters (question and depth). The description adds value by explaining what each depth tier does behaviorally (quick=3 facets, standard=5+gap recovery+contradictions, thorough=8+chases leads), which the enum names alone would not convey. Also clarifies that broad/multi-part questions are fine, adding intent guidance beyond schema.

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

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

The description states a specific verb+resource ('Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources') and clearly distinguishes from siblings: it is NOT open-web search, uses 5,347 tools in parallel, and explicitly contrasts with ask_pipeworx ('For a single lookup use ask_pipeworx'). It also differentiates from the news-focused ask_pipeworx for current 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?

Extremely explicit about when to use and when NOT to use: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Names the alternative tool directly and gives concrete example queries for each case.

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 readOnly, idempotent, not destructive. Description adds that results include full schemas with examples and are ready to call directly, no second lookup needed. Does not contradict annotations.

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

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

Description is informative and front-loaded with purpose. Slightly long but all sentences add value. Not wasteful.

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

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

Covers purpose, usage context, return value (full schemas with examples), and default/max limit. No output schema, but description compensates by explaining what is returned.

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 100% with descriptions for each parameter (query, aliases, limit). Description mentions query and limit but adds little beyond schema. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

States specific verb 'Find' and resource 'tools'. Lists broad domain categories (SEC filings, financials, etc.) and distinguishes from siblings by being the only tool discovery tool among many specialized 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?

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set'. Provides context by listing many domains. Lacks explicit when-not-to-use but clearly positions its role.

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

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

Discloses multiple behavioral traits: fans across SEC, XBRL, USPTO, news, GLEIF; returns specific fields including CIK, filings, fundamentals, patents with sunset note, news, LEI; soft-fail behavior for patents. Adds value beyond annotations (readOnlyHint, etc.).

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

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

Well-structured: starts with examples, then succinct purpose, then bullet-like list of returned data, ending with input constraints. Every sentence adds value 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 no output schema and complex tool with multiple data sources, the description is highly complete: covers all inputs, outputs, limitations, and usage context. No gaps identified.

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

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

Schema coverage is 100% with descriptions; description adds extra meaning: value can be ticker or zero-padded CIK, names not supported. Clearly differentiates valid input formats.

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

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

Description uses specific verb and resource: 'full cross-source profile of a US public company'. Provides concrete command examples and distinguishes from sibling tool 'resolve_entity' that handles names.

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 ('always prefer over chaining... when user asks for holistic view') and when not to use ('names not supported, use resolve_entity first').

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

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

Annotations already indicate destructiveHint=true. The description adds that it clears sensitive data, providing additional behavioral context. 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?

Two concise sentences, front-loaded with the core action. Every sentence adds value 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?

For a simple delete tool with full annotations and schema coverage, the description covers purpose, usage, and pairing sufficiently. No output schema needed for a delete operation.

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

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

The single 'key' parameter is fully defined in the schema with 100% coverage. The description mentions 'by key' but adds no additional semantics 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 'Delete a previously stored memory by key', which is a clear verb+resource. It explicitly mentions pairing with 'remember' and 'recall', 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?

Provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with remember and recall, guiding alternative choices.

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, idempotentHint, and non-destructive. The description adds context about fetching the page, extracting title/description/key links, and emitting markdown, which aligns with annotations and provides extra behavioral detail.

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

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

Three sentences, front-loaded with purpose, no wasted words. Well-structured and efficient.

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

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

For a simple tool with 2 params and high schema coverage, the description covers output format, use cases, and process. No output schema needed; description is sufficient.

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

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

Schema description coverage is 100% with clear parameter descriptions. The description adds value by explaining the process (fetches, extracts, emits) and output format, which goes beyond the schema alone.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, specifying the output format and use cases. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on file generation.

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

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

The description lists explicit use cases (client's site indexing, drafting for own project, auditing competitor) but does not explicitly state when not to use it. Clear context provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds minimal behavioral context beyond listing return fields. It does not mention what happens on error (e.g., invalid ID) or any side effects. With annotations covering safety, the description's contribution is limited.

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

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

Two sentences with no wasted words. The first sentence states the purpose directly, and the second lists return fields. Ideal front-loading 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?

Given the lack of output schema, the description partially compensates by listing return fields. It does not mention error handling or response format, but for a simple get-by-ID tool with rich annotations, it is reasonably complete. Slightly more detail about return structure would be beneficial.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by specifying the returned data (email, name, etc.), indirectly clarifying the purpose of the 'id' parameter. However, it does not elaborate on _apiKey or account beyond the schema, so it slightly exceeds the baseline of 3.

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

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

The description uses the specific verb 'Get' and resource 'contact by ID', clearly indicating it retrieves a single contact. It lists the returned fields (email, name, phone, custom fields, engagement details), distinguishing it from sibling tools like list_contacts which returns multiple contacts.

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

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

The description implies usage for fetching a single contact by ID, but does not explicitly state when to choose this tool over alternatives (e.g., list_contacts for lists, search_within for queries). No exclusions or context about prerequisites are provided, making it adequate but lacking explicit guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds specific detail about returned data (IDs, names, status, counts), providing value beyond annotations without contradiction.

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

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

Single sentence that is concise, front-loaded with the verb and resource, and contains no filler. Every word earns its place.

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

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

For a list tool with 100% schema coverage, annotations, and no output schema, the description adequately covers what the tool does and returns. No gaps for typical usage.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description does not add new parameter information, so 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 uses specific verb 'List' and resource 'marketing automations (workflows)', and specifies return fields (IDs, names, status, enrolled-contact counts), clearly distinguishing it from sibling list tools like list_campaigns or list_contacts.

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

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

The description implies usage for listing automations but offers no explicit guidance on when to use this tool vs alternatives (e.g., list_campaigns), nor any exclusion criteria. Agents must infer usage from context.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, covering the safety profile. The description adds return field details but omits behavioral traits like pagination, ordering, 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?

Single sentence is highly concise and front-loaded with the verb and resource. Every word adds value.

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

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

Describes return fields but missing details on pagination, limit behavior, or filtering. Given no output schema, the description partially compensates but could be more complete for a list tool.

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

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

Schema coverage is 100%, with descriptions for all three parameters. The description adds no extra meaning to the parameters beyond what the schema provides, meeting the baseline.

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

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

The description clearly states the tool lists email campaigns with specific metrics and return fields. It distinguishes from sibling list tools (e.g., list_contacts, list_automations) by specifying the resource type and data included.

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

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

No guidance on when to use this tool versus alternatives like list_automations or list_contacts. Does not mention prerequisites, filtering, or context where this tool is preferred.

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 fully declare read-only, idempotent, non-destructive. The description adds return structure (IDs, emails, names, meta.total). No contradiction; could mention pagination behavior but not required.

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

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

Two sentences, front-loaded with purpose, efficient and no fluff.

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

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

Covers purpose, filters, return shape, and safety (via annotations). Missing explicit mention of pagination, but limit param in schema provides that. Sufficient for correct use.

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

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

Schema covers all 5 parameters with descriptions (100% coverage). The description adds context by explaining the relationship between email and search filters, and what the return includes, complementing the schema.

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

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

The description explicitly states the action ('List/search') and resource ('contacts/subscribers'), and distinguishes from siblings like 'get_contact' by mentioning filtering options and return fields (IDs, emails, names, meta.total).

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 clearly states when to use email for exact match and search for free-text, but does not explicitly exclude alternatives like get_contact for single contact by ID, nor mention pagination or ordering.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already indicate safe read operations. The description adds value by detailing the response structure (deal IDs, titles, values, stages, owners, meta.total), which goes beyond annotations.

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

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

Single sentence front-loading the action and resource, followed by concise details on return fields. No extraneous words.

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

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

No output schema is provided, but the description compensates by listing returned fields. It covers the essential information for a list tool, though additional details on pagination or sorting are absent.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description does not add parameter-level meaning beyond the schema, meeting baseline expectations.

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 CRM deals (sales pipeline opportunities) and specifies the returned fields (deal IDs, titles, values, stages, owners, meta.total). It is distinct from sibling list tools like list_contacts or list_campaigns.

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

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

No explicit guidance on when to use this tool versus sibling list tools. The description is functional but lacks context about preferred scenarios or prerequisites.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, so the tool is safe and non-destructive. The description adds concrete output fields (list IDs, names, subscriber counts, creation dates), which helps agents understand what data to expect. No contradictions with annotations.

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

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

The description is a single, front-loaded sentence that immediately communicates the action ('List contact lists') followed by specific return details. No extraneous words or repetition.

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

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

Given the tool's simplicity (3 parameters, no output schema, no nested objects), the description covers purpose and return structure adequately. However, it lacks details on pagination or result ordering, which would improve completeness for an agent.

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

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

Schema description coverage is 100%, with each parameter (limit, _apiKey, account) fully explained. The tool description does not add additional semantics beyond restating output fields. 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 lists contact lists and specifies the returned fields (IDs, names, subscriber counts, creation dates). This distinguishes it from sibling tools like list_contacts (which lists contacts) and get_contact (single contact). The verb and resource are explicitly defined.

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

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

No explicit guidance on when to use this tool versus alternatives. The description implicitly suggests it is for retrieving an overview of all lists, but does not mention when to use it over specific list retrieval tools (if any existed) or any prerequisites. Sibling tools are not addressed.

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. The description adds that it returns specific fields and implies default behavior (active only). This adds some context but does not reveal significant behavioral traits beyond the annotations.

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

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

The description is two sentences, each serving a distinct purpose: defining the tool and providing usage guidance. No unnecessary words.

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

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

Given the simple tool with one optional parameter and annotations, the description covers purpose, return fields, and usage context. It lacks explicit mention of default filtering or pagination, but is sufficient for a basic list operation.

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

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

Schema coverage is 100% with a clear description for the only parameter. The description does not add new meaning about the parameter beyond what the schema provides, but the phrase 'active subscriptions' implicitly relates to the include_inactive 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 explicitly states the tool lists the caller's active subscriptions, with specific fields returned. This clearly distinguishes from sibling tools like subscribe and unsubscribe.

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

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

The description provides contextual usage: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This guides when to use the tool relative to subscribe/unsubscribe, but does not explicitly list alternatives or when not to use.

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

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

Annotations are all false. The description adds behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against quota, and team reads daily. This provides useful transparency beyond annotations, though it could mention if the operation is synchronous or async.

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 (3 sentences) and well-structured: purpose first, then usage guidelines, then behavioral notes. Every sentence adds value 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 3 parameters (one with enum, one nested) and no output schema, the description covers purpose, usage, and behavioral constraints adequately. It could mention the return value or acknowledgement, but for a feedback tool this is sufficient.

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

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

Input schema has 100% description coverage, so parameter meaning is clear. The description adds practical guidance on how to write the message (be specific, reference tools/packs, 1-2 sentences). This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verb 'Tell' and resource 'Pipeworx feedback', distinguishing it from sibling tools which are unrelated.

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 details when to use the tool (bug, feature, data_gap, praise) and provides anti-patterns (don't paste end-user prompt). Also mentions team reads digests daily and rate limits, giving clear context for appropriate use.

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

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

Description adds value beyond annotations: it discloses the data source (CF analytics-engine), privacy (no PII), structure (pack, tool, count), and caching behavior (5min-1h). Annotations already indicate read-only, idempotent, non-destructive.

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

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

Description is efficient, front-loaded with purpose, followed by bulleted use cases, and then technical details. Every sentence adds value, no redundancy.

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

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

No output schema exists, so description should specify return format more precisely. It says 'just (pack, tool, count)' but not whether it's an array, what the exact field names are, or pagination. This may leave the agent uncertain about how to parse the response.

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 enum and description. The description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose the window appropriately.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a window, with a specific verb 'Returns'. This differentiates it from sibling tools like discover_tools by focusing on trending 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?

Three explicit use cases are provided (discovering hot data sources, confirming canonical tool, aligning use case). While it doesn't name alternatives, the context is clear. Could be improved by mentioning when not to use (e.g., for historical analysis).

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral context: walking child markets, ordering checks, partition_sum computation, fill check against CLOB depth, semantic anchor, placeholder filtering. No contradictions with annotations.

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

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

The description is detailed but structured with clear sections (modes, semantic anchor, partition filter, fill check). Front-loaded with purpose. Slightly verbose but every sentence adds value, earning a high score.

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

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

No output schema, but the description fully explains return values: opportunities array with fields, partition_check object, fill check details. Also covers edge cases like skipped_low_similarity, placeholders, and trade advisories. Complete for a complex arbitrage tool.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains event slug format, accepts full URLs, describes topic as seed question and cross-event scanning. Goes well beyond schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by specifying its unique methods and resource.

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

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

The description explicitly explains when to use each mode: no args for trending scan, event for specific market, topic for cross-event. It provides recommendations and explains when not to use (e.g., fill check signals not to trade). This is comprehensive 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: three model segments, edge calculation (edge_pp_net after slippage, kelly_fraction, 24h-move warning), tradeable-edge filters, caching behavior (1h at KV level), and diagnostics sections. No contradiction with annotations.

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

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

The description is verbose (over 400 words) and contains dense technical details. While well-structured with parenthetical explanations, it could be more concise. Some sentences are long and packed with information, potentially overwhelming an AI agent.

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

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

Given 9 optional parameters and no output schema, the description thoroughly explains the response structure (by_segment with three segments, diagnostics, fed_candidates) and how each parameter affects results. It provides enough context 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 coverage is 100%, so baseline 3. The description explains each parameter in detail, including defaults and context (e.g., slippage_pp explains typical bid/ask depth, min_partition_leg_kelly explains relationship to partition Kelly). Adds significant meaning beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the resource (Polymarket markets) and the action (scan and return opportunities), and distinguishes from siblings like polymarket_arbitrage by mentioning Pipeworx data and the three response segments.

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 it's built for 'what should I bet on today' and that agents can discover opportunities without paging hundreds of markets. It also explains tradeable-edge knobs (min_liquidity, max_spread_pp) and when to use them. However, it does not explicitly state when not to use or mention alternative sibling tools.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: data from daily snapshots with gaps, 60-day TTL, decay computed from daily closes, and response 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 well-structured with clear sections for response fields and limits. It is somewhat long but every part adds value; could be slightly more concise.

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

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

With no output schema, the description fully explains the return structure (tracked, expired, snapshot_dates fields) and limitations (60-day TTL, gaps, decay calculation). It is complete for a tool of this complexity.

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

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

Schema coverage is 100% and both parameters are adequately described in the schema. The description adds minor clarification (e.g., 'max 30' vs schema's 'clamp 2-30') but does not significantly enhance meaning beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question about how long edges have existed and whether they are shrinking, distinguishing it from sibling tools that list current edges.

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

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

The description explains the use case (differentiating fresh vs. old edges) but does not explicitly exclude alternative tools or provide when-not-to-use guidance. It implies usage context well.

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?

All annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent with the description, which never implies mutation. The description adds behavioral detail: it explains the risk of partial basket fills converting arb into directional position, walking the ladder, and default behaviors. No contradictions with annotations.

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

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

The description is somewhat long but well-structured: it starts with the core purpose, then covers required parameters, modes, and returns. It uses bold and capitalization for key points (REQUIRES, SINGLE-MARKET, BASKET). Every sentence is necessary given the tool's complexity, but minor tightening could improve conciseness.

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

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

With no output schema, the description thoroughly documents return values for both modes, including risk indicators like thin_legs and forced_directional_risk. It covers default values, clamping, and the main use case. It does not specify error behavior or URL format, but these are minor omissions given the overall completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful nuance: for `side`, it explains auto-default logic for baskets; for `size_usd`, it clarifies interpretation as settlement notional in basket mode. These additions enhance understanding beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, lists return fields, and explicitly directs to use before acting on arbitrage or edge signals, differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround on thin books is not capturable, partial basket fills create directional risk) and specifies required parameters (market or event). This clearly tells when and when not to use the tool.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral details: two input modes, response structure (leg-by-leg prices, top_spreads_pp, compatibility warning, temporal alignment, skipped counters), and honest limitations (most pre-mapped topics not tradeable). 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?

Well-structured with front-loaded purpose, then modes, response, and safety fields. Every sentence adds value, though slightly verbose in places. Overall efficient and clear.

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

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

Despite no output schema, the description thoroughly explains the response: leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters. An agent can fully understand inputs and outputs without additional documentation.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining the topic parameter lists and how explicit parameters override the topic side. It connects parameters to modes, enhancing understanding beyond schema descriptions.

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

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

The description clearly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' specifying the verb (compute spread) and resource (cross-venue spread). It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison, not single-venue arbitrage.

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

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

The description explicitly explains two modes (topic shortcuts and explicit ticker-slugs) and provides detailed safety fields like compatibility_warning and temporal_alignment. It warns when spreads are meaningless and states that pre-mapped topics often return warnings, guiding the agent on when to use and what to expect.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful context: scoping to identifier (anonymous IP, BYO key hash, account ID) and the 'list all' behavior when key is omitted. 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?

Two sentences, no wasted words. Action verb first, front-loaded with key information. Each sentence adds essential 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 read-only tool with one optional parameter and annotations covering safety, the description is fully complete. It explains the tool's purpose, usage, scoping, and relationship with siblings. No output schema needed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that omitting the key parameter lists all saved keys, which is not explicitly in the schema description. This clarifies the optional nature and dual 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 uses specific verbs ('Retrieve', 'list') and clearly identifies the resource (values saved via remember, all saved keys). It distinguishes from sibling tools 'remember' and 'forget' by name, and states the dual behavior (single key retrieval vs. listing all).

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

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

Explicitly says when to use ('look up context the agent stored earlier') and when to omit key (list all). Mentions pairing with 'remember' and 'forget', and notes scoping by identifier. Provides clear guidance with no ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details like 'mark_read:true' flagging events as read and the return fields, which go beyond annotations. No contradictions.

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

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

Description is concise and efficiently structured. Front-loaded with purpose, then details on return values, filtering, and a note on polling. Every sentence adds value, no fluff.

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

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

Given 5 optional parameters and no output schema, the description covers return fields (source, citation_uri, raw payload), filtering options, and alternative access method. Adequately complete for a read-only tool with clear 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% (baseline 3). The description adds meaning to parameters: explains 'since' expects ISO timestamp, 'mark_read' behavior, 'unread_only' meaning, and 'type' filter. Provides extra context beyond schema descriptions.

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

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

Clear verb ('Pull') and specific resource ('fired events from your subscription feed'). The description distinguishes the tool from siblings by focusing on alerts retrieval and mentions specific fields returned.

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 guidance on filtering (type, since) and mentions polling is acceptable. Also offers an alternative HTTP endpoint for scripts/dashboards, aiding context. However, it doesn't explicitly state when not to use the tool.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds substantial behavioral details: it fans out to multiple sources (SEC, GDELT→GNews fallback, USPTO), explains fallback logic and soft-fail conditions, and specifies return structure (grouped changes, count, citation URIs). No contradiction with annotations.

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

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

The description is a single paragraph but packs essential information: example queries, core functionality, data sources, parameter guidance, return format, and sibling tool recommendation. No redundant sentences; every part earns its place.

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

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

Given no output schema, the description adequately covers return structure (changes[], total_changes, citation URIs). It explains all parameters and source behavior. Minor omission: no explicit mention of maximum window or pagination, but the tool's purpose (recent changes) makes these non-critical.

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 practical meaning: explains that `since` accepts ISO date or relative shorthand and recommends '30d' or '1m'; notes that `type` only supports 'company' for now; clarifies that `value` can be ticker or zero-padded CIK. This is useful context beyond the schema descriptions.

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

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

The description clearly states the tool's function: 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It also distinguishes from the sibling tool entity_profile by directing users to use entity_profile for static profiles. This meets the criteria of a specific verb+resource and sibling differentiation.

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

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

The description provides example user queries and explicitly advises when to use a sibling tool ('Use entity_profile instead when you want the static profile...'). It also explains the fan-out behavior and parameter recommendations (e.g., 'Use "30d" or "1m" for typical monitoring'). However, it could mention when not to use this tool in favor of other siblings like recent_alerts, but overall 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 indicate idempotentHint=true and destructiveHint=false. The description adds behavioral details like scoping by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. No contradictions with annotations.

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

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

The description is a single, well-structured paragraph with no wasted words. It front-loads the purpose, then usage, then behavioral specifics, and ends with pairing to siblings.

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 and 100% schema coverage, the description is complete. It covers purpose, usage, scoping, retention, and companion tools. No output schema exists, but return values are not needed for a write operation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds naming conventions (e.g., 'subject_property', 'target_ticker') and clarifies that value can be any text, which adds helpful context beyond the schema.

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

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

The description begins with a clear action verb 'Save' and specifies the resource 'data the agent will need to reuse later'. It explicitly distinguishes itself from sibling tools like 'recall' and 'forget' by mentioning them as complementary tools.

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

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

The description provides explicit guidance on when to use: 'Use when you discover something worth carrying forward'. It also pairs with 'recall' to retrieve and 'forget' to delete, giving clear context for 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 the tool as read-only, idempotent, and non-destructive. The description adds value by revealing internal cascading lookups and specifying exact return fields (ticker, CIK, RxCUI, etc.), which annotations do not cover. No contradictions.

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

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

Description is well-structured with examples first, then purpose, then detailed type breakdown. It is informative without being verbose, though the examples could be slightly condensed. Every sentence adds value.

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

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

Given no output schema, the description compensates by detailing return values for each type (including citation URIs). The two parameters are fully documented with examples, and annotations cover safety. The tool's complexity is low, so this 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 coverage is 100%, but the description adds meaningful context beyond schema descriptions: for the 'type' enum, it explains what each value returns; for 'value', it provides concrete examples (e.g., ticker, CIK, or name). This enhances the agent's understanding of parameter usage.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific examples ('What's the ticker for...') and supported types (company, drug). It distinguishes from siblings by emphasizing it as the first step when needing an ID, contrasting with other tools like entity_profile that provide more detail.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear context for when to invoke. It details inputs and outputs per type but lacks explicit alternatives for cases when an ID is already known, though the implication 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the tool probes each entity with 'ai_visibility_check', ranks by score, and returns a ranked list with specific fields (score, confidence, signal density), going beyond the annotations. 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?

Four sentences, front-loaded with the primary action, no wasted words. Every sentence adds value: purpose, behavior, use case, output format.

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

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

For a multi-entity comparison tool with 4 parameters and no output schema, the description covers purpose, usage, and return fields (score, confidence, signal density). Missing error conditions or rate limits, but annotations mitigate some gaps.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description adds context: 'First entry treated as the "subject" for narrative; rest are competitors,' which aids understanding. This exceeds the baseline of 3.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), clearly distinguishing from sibling tools like 'ai_visibility_check' (single entity) and 'compare_entities' (general comparison). It states the tool probes entities, ranks by score, and surfaces most/least recognized.

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 a concrete use case ('competitive AI-marketing audits') with an example question, and implicitly distinguishes from single-entity probing. However, it lacks explicit when-not-to-use statements or mention of 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 provide readOnlyHint, openWorldHint, idempotentHint. Description adds crucial behavioral details: partial failure graceful degradation, bundlephobia first measurement timing (5-30s), and sources_failed reporting. No contradiction with annotations.

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

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

Description is longer but every sentence adds value. Front-loads key purpose and constraints. Could be slightly more concise, but structure is clear and logical.

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

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

No output schema provided, but description compensates by listing expected return fields (summary block, per-advisory detail, links, alternative versions) and error handling. Complete enough for agent to understand outcomes.

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

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

Schema coverage is 100% with both parameters described. Description adds value by noting version defaults to latest and confirming scoped packages are accepted. While baseline is 3 due to high coverage, the added context earns a 4.

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

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

Description explicitly states the tool performs a composite check for adding npm packages, aggregating data from deps.dev and bundlephobia. It clearly distinguishes from sibling tools by specifying NPM ecosystem only and directing other ecosystems to deps.dev:version.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides exclusion criteria: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses the embedding model (BGE-base-en), window size (500 char overlapping), chunking strategy, and character cap with truncation behavior. This adds significant transparency.

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

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

The description is concise with 3-4 sentences, each earning its place. It front-loads the purpose, then provides usage context, pairing suggestion, and technical details. Zero waste.

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

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

Given no output schema, the description explains return values (passages with offsets, similarity scores) and edge cases (truncation with flag). It is complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds usage context for parameters, e.g., 'Pass the text you already pulled' for text and 'natural-language query' for query. It also explains that limit controls top-N passages with default 5. This adds meaningful value beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verbs and resource. It explains that the tool returns passages with offsets and similarity scores, but it does not explicitly differentiate from sibling tools like deep_research or validate_claim, slightly reducing clarity.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and provides a specific alternative: 'Pairs with ask_pipeworx_grounded'. This gives clear when-to-use and alternative guidance.

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

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

The description details behavioral traits beyond annotations: it explains the return value (subscription ID), OAuth requirement, type-specific behavior, delivery channels, constraints (SMS cap, phone verification), and webhook signing. No contradiction with annotations.

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

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

The description is well-structured, starting with the main purpose, then prerequisites, types, and delivery options. It is fairly long but every sentence provides value. Could be slightly more concise.

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

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

Given the complexity (multiple types, delivery channels, OAuth requirement), the description is comprehensive. It covers prerequisites, type-specific parameters, delivery constraints, and confirms the return value. No output schema, but the return is adequately described.

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

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

Schema coverage is 100%, but the description adds significant meaning with type-specific parameter formats (e.g., sec_8k items codes) and delivery channel explanations (e.g., webhook HMAC signing). This goes well beyond the schema's descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It specifies the verb 'create', the resource 'subscription', and the domain, distinguishing it from siblings like unsubscribe or list_subscriptions.

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

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

It explicitly requires a Pipeworx OAuth account and explains that anonymous/BYO cannot persist subscriptions. It provides type-specific examples but does not explicitly contrast with alternatives like recent_alerts for reading.

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, and non-destructive hints. Description adds valuable context: it returns example questions with exact tool+argument shape, and is drawn from a live catalog of thousands of tools, enhancing transparency beyond annotations.

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

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

The description is information-dense but well-structured, front-loading example queries and key usage guidance. While slightly lengthy, every sentence adds value, making it concise for the amount of context provided.

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

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

Given no output schema, the description fully explains the output format (category-bucketed examples with tool+argument shape) and the optional parameter effect. It covers all necessary context for a read-only, non-destructive discovery tool.

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

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

Schema coverage is 100% with a single optional topic parameter. Description adds specific example values (finance, pharma, etc.) and explains behavior when omitted (full spread), providing meaning beyond the schema.

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

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

The description clearly states it is the onboarding entry point for a new agent to discover what Pipeworx can do, returning category-bucketed example questions. It distinguishes itself from siblings like ask_pipeworx by being a discovery tool rather than an execution tool.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do', providing clear when-to-use guidance. Also explains how to optionally pass a topic to focus, and that it helps learn how to call meta-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?

Adds beyond annotations: describes deactivation (not deletion) and that historical events remain via recent_alerts. Annotations already give idempotentHint and destructiveHint.

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

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

Three focused sentences with no wasted words. Front-loaded purpose.

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

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

Adequate for a simple tool with one parameter and no output schema. Covers purpose, constraint, and effect.

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 does not add significant meaning beyond what the schema already provides for the single 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?

Clearly states the verb 'Cancel' and resource 'subscription by id'. Distinct from siblings like subscribe and list_subscriptions.

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

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

Mentions ownership enforcement ('only cancel your own subscriptions'), providing when-to-use guidance. Does not explicitly name alternatives but context is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral detail: two processing paths (SEC EDGAR for financial claims, grounded pipeline for others), exact percent-delta math, verbatim evidence, and that it replaces multiple sequential calls. No contradictions with annotations.

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

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

The description is verbose but well-structured, with examples and a clear outcome. It could be more concise by removing some repetitive example phrases, but it effectively communicates the tool's functionality.

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 fully explains the return value (verdict, actual value with citation, reasoning). It covers all parameters, behavioral nuance, and use cases, leaving no gaps for an agent to misunderstand.

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?

Both parameters have clear descriptions in the schema (100% coverage). The description enhances this by explaining that tolerance_pct overrides the default implied by wording (capped at 5), which adds meaningful context.

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

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

The description clearly states it is a natural-language claim verification tool, lists example query patterns ('Is it true that…', 'fact check'), and distinguishes between financial and other claims. This is specific and distinct from sibling tools like 'ask_pipeworx_grounded' or 'deep_research'.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes the fast path vs. grounded pipeline, guiding when each applies. However, it does not explicitly list alternative tools or when not to use it.

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