Intercom

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

The description fully discloses behavioral traits: it queries LLMs, requires API key for Anthropic (passed straight through, no storage), and returns per-model and combined views. Annotations already mark it as read-only, idempotent, and non-destructive; the description adds context about API key handling and missing default model compensation, without contradicting annotations.

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

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

The description is concise (3 sentences), front-loaded with the main purpose, then details on parameters and use cases. Every sentence adds value with no redundancy or fluff.

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

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

Given the full schema coverage and no output schema, the description adequately explains the return structure (per-model score, confidence, signals, raw_response + combined view). It also addresses intended use cases, making it complete for this tool's complexity.

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

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

Schema description coverage is 100%, yet the description adds significant value: it explains the default model ('Workers AI Llama-3.3-70b free'), clarifies that '_apiKey' is optional and required only for Anthropic, and describes 'context' as disambiguation aid. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's function: probing LLMs for brand visibility and scoring them 0-100 per model. It uses specific verbs ('probe', 'score'), defines the resource (LLMs), and the output format. The description also differentiates this tool from siblings by focusing on AI-marketing audits and brand checks, providing context that distinguishes it from similar tools like scan_competitor_ai_presence.

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

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

The description provides clear usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to use the default model and how to add Anthropic with an API key. However, it does not explicitly mention when not to use this tool or provide direct comparisons to sibling tools, which would elevate the score to 5.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate safe, read-only, non-destructive behavior. The description adds significant behavioral context: routes to 3,745 tools across 884 verified sources, fills arguments, and returns structured answers with stable pipeworx:// 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?

The description is well-structured: starts with a strong directive, lists supported domains, explains the routing mechanism, gives usage clues, and ends with examples. Every sentence adds information without redundancy. It is concise yet comprehensive.

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 (routing to thousands of tools) and lack of output schema, the description is remarkably complete. It covers scope, usage, and output format (structured answer with citations). The examples are relevant and diverse. No obvious gaps.

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

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

Schema coverage is 100% with multiple aliases and a clear description. The description adds value by explaining that the question is used for routing to the right tool and filling arguments, and it provides concrete examples. This is slightly beyond the schema, so a 4 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 routes a natural language question to a large set of authoritative sources and returns a structured answer with citations. It distinguishes itself from web search and lists specific domains and use cases (e.g., SEC filings, FDA drug data), making its purpose unmistakable.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides detailed guidance on when to use: for factual questions about real-world entities, events, or numbers, with specific examples like 'current US unemployment rate' and 'Apple's latest 10-K'. It also lists trigger words ('what is', 'look up', 'find'). This helps the agent decide between this tool and 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?

The description discloses the underlying mechanism (picking the right tool, fetching data, extracting answer only from tool result), return structure with evidence and confidence, and refusal reasons. Annotations already declare readOnlyHint and idempotentHint, so the description adds substantial behavioral context without contradiction.

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

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

The description is four sentences long, front-loaded with the key purpose, and every sentence adds value. It could be slightly more concise, but it is well-structured and avoids 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?

Despite lacking an output schema, the description fully explains the return format and potential refusal reasons. It also notes the extra LLM call cost, making the tool's behavior completely transparent for complex multi-agent 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% and all parameters are aliases for the question string. The description lists the aliases but does not add significant meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, distinguishing it from ask_pipeworx by specifying the extraction mechanism and use cases. It uses specific verbs like 'extracts' and 'returns' and explicitly lists refusal reasons.

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

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

The description provides explicit when-to-use (high-stakes reads where answer will be quoted/cited/acted on) and when-not-to-use (prefer ask_pipeworx for casual lookups). It also gives concrete examples of domains like financial verdicts, legal claims, medical lookups, and public statements.

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 extensively details behavioral traits beyond annotations: fan-out parallel calls, response shape, resolver contract, parent event extraction, news fallback mechanisms, safety short-circuits, closed market handling, wide-spread indicators, 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 front-loaded with the main purpose, but becomes quite verbose with extensive technical details and examples. While comprehensive, it could be more concise without losing necessary information.

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

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

Given the tool's complexity (multiple fan-out paths, resolver contract, parent events, news fields, safety mechanisms, resolution rules) and absence of an output schema, the description is exceptionally complete, covering edge cases and return values in detail.

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

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

Schema covers all three parameters with descriptions, achieving 100% coverage. The description reinforces parameter meanings (e.g., market input types) and adds examples, but doesn't significantly augment the schema's semantic content.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, specifying inputs and outputs. It distinguishes from sibling tools implicitly through its unique focus on evidence packet generation, but does not explicitly differentiate from similar Polymarket tools.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and examples of fan-outs. It lacks explicit when-not-to-use guidance, but the given context is sufficient.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses specific data pulled for each entity type: company (10-K revenue, net income, cash, debt from SEC EDGAR/XBRL) and drug (FAERS adverse events, FDA approvals, active trials). It also mentions off-calendar fiscal year handling and results sorting. 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 dense but not overly long; it front-loads usage triggers and includes bold directives. It could be slightly more structured (e.g., bullet points for entity types), but every sentence adds value. Minor room for improvement.

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

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

The description covers all essential aspects: purpose, usage preference, data sources, fiscal year handling, sorting, and output format (paired data with citation URIs). No output schema exists, so the description sufficiently explains return values. Complete for a complex tool.

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

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

Schema coverage is 100%, but the description significantly enriches parameter meaning. For 'type', it explains what data is retrieved for each enum value. For 'values', it specifies input formats (tickers/CIKs for company, names for drug) and the count range (2-5). It also clarifies that results are sorted by primary metric.

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 concrete natural language triggers ('Compare X and Y', 'which is bigger') and clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes itself from sequential lookups, making the purpose immediately clear.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a strong directive on when to use this tool over alternatives. It also explains the data sources for each entity type, giving 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?

Annotations (readOnlyHint, idempotentHint, no destructive) are complemented by description detailing parallel execution, evidence with citations, explicit gaps, no invention, and time estimates. 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 comprehensive and front-loaded with the key value proposition. Every sentence adds value, though it is slightly lengthy at ~100 words. Very efficient overall.

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

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

Given the tool's complexity (parallel research, many sources), the description fully covers purpose, process, output structure, prerequisites, and caveats. No output schema exists, but the description appropriately 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 covers 100% parameters, but description adds valuable context: question can be broad/multi-part, depth defaults to standard, thorough requires paid plan, and explains the quick/standard/thorough facet counts.

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

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

The description clearly states the tool performs grounded multi-source research in one call, decomposes questions, and returns structured findings. It distinguishes from sibling ask_pipeworx by specifying single lookups vs. broad 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 recommends use for broad/multi-part questions with examples, and advises using ask_pipeworx for single lookups. Also mentions prerequisites (Pipeworx account) and plan requirements for depth parameter.

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

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

Annotations already indicate read-only and idempotent. Description adds that it returns top-N relevant tools with full schemas and examples, ready to call directly, and that no second schema lookup is needed. This enriches behavioral understanding beyond annotations.

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

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

Description is front-loaded with purpose, then lists domains, then explains output. It is slightly verbose with the domain list but each part adds value. Could be trimmed slightly, but generally concise.

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

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

Despite no output schema, the description thoroughly explains what is returned (top-N tools with names, descriptions, full schemas, examples) and that results are directly callable. This covers all necessary context for an agent.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by listing aliases for query (task, q, description, search) and stating default and max for limit. Examples are provided in the schema, which is helpful.

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

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

Description clearly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, financials, etc.), making it distinct from sibling tools like deep_research or entity_profile. It specifies the action (discover) and resource (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 'Use when you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and differentiates from other 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description details the tool's parallel fan-out across multiple APIs, includes a known soft-failure (USPTO PatentsView API sunset), and specifies the structure and limits of return data (e.g., up to 5 filings, latest fundamentals sorted).

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

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

The description is a single dense paragraph that efficiently packs examples, usage, and behavioral notes. It is well-organized but could benefit from slight structuring (e.g., bullet points) for even easier scanning. 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?

Without an output schema, the description fully explains what the tool returns (cik, company_name, recent_filings with URIs, fundamentals, patents with sunset note, news, LEI). It covers input constraints, parallel calling behavior, and fallback mechanisms, making it complete for an agent to use correctly.

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

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

Schema coverage is 100% and each parameter has a clear description. The description adds context about accepted formats (ticker vs. zero-padded CIK) and the unsupported name input, going slightly 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 that the tool produces a 'full cross-source profile of a US public company in ONE parallel call,' listing specific data sources and return fields. It distinguishes itself from chaining individual lookups by emphasizing it should be preferred for holistic views.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies input constraints (ticker or zero-padded CIK, not names) and directs to use resolve_entity if only a name is available.

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 destructiveHint true. The description adds context on why deletion is appropriate (stale data, sensitive data), enhancing behavioral understanding 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?

Two sentences, front-loaded with the primary action, and every word adds value. No redundancy or unnecessary detail.

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 one parameter, the description, schema, and annotations together provide complete context. Output schema not required as return is straightforward.

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

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

Schema provides 100% coverage for the single 'key' parameter with a clear description. The tool description adds no additional parameter information, so baseline 3 is appropriate.

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

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

The description explicitly states the action ('delete') and resource ('previously stored memory by key'), clearly distinguishing it from sibling tools like 'remember' and 'recall'.

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

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

Provides explicit when-to-use cases (stale context, task done, clear sensitive data) and mentions pairing with 'remember' and 'recall', but lacks explicit when-not-to-use or alternative tools.

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

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

Annotations already indicate idempotent, read-only, and non-destructive behavior. The description adds the exact steps (fetches, extracts, emits) and the output format, which goes beyond annotations. No contradiction found.

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

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

The description is a single, well-structured paragraph that front-loads the purpose and follows with details. Every sentence adds value, and there is no extraneous information.

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

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

Given the simple tool (2 parameters, no output schema), the description fully explains the behavior, output format, and use cases. Combined with clear annotations, it provides complete context for an agent.

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

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

The input schema covers 100% of parameters with descriptions. The tool description does not add new parameter details beyond what the schema provides, but it reinforces the purpose of the 'url' parameter. 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 ('generate', 'fetches', 'extracts', 'emits') and clearly identifies the resource ('llms.txt file for any URL'). It distinguishes itself from sibling tools by specifying the exact output and use cases.

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 concrete use cases (client's site indexing, drafting for own project, auditing competitor) but does not explicitly state when not to use it or suggest alternatives. However, the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about returned fields (name, email, phone, attributes, tags, conversation history), but the behavioral traits are well-covered by 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 sentence that efficiently states the purpose and key return fields. No unnecessary information.

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

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

Given the tool is a simple get-by-ID with a single required parameter and an output schema (as indicated by 'Has output schema: true'), the description is complete. It lists the major return fields, and the schema covers the rest.

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

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

The input schema has 100% description coverage (the single parameter 'id' is described as 'Contact ID'). The description does not add further parameter details, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('full contact details by ID'), clearly distinguishing it from siblings like ic_search_contacts (search) and ic_get_conversation (different 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 clearly states when to use (when you have a contact ID and want full details), but does not explicitly mention when not to use it or alternative tools. The sibling list includes ic_search_contacts, which implies an alternative for searching without an ID.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the description's job is lighter. It adds value by specifying that the full thread is returned with all messages, timestamps, participants, and metadata, which is not in annotations. No contradiction exists.

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

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

The description is a single concise sentence that front-loads the core action and details. Every word 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?

Given the presence of an output schema (from context), the description is sufficient for a simple get-by-ID tool. It covers what the tool does and what it returns. No missing information.

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

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

Schema coverage is 100% with a single `id` parameter described as 'Conversation ID'. The description does not add further parameter-level detail, but schema already handles it. 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 action (Get), the resource (complete conversation thread by ID), and enumerates what is returned (messages, timestamps, participants, metadata). This distinguishes it from sibling tools like `ic_list_conversations` and `ic_get_contact`.

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 retrieving a specific conversation by ID, but does not explicitly state when to use it versus alternatives like `ic_list_conversations` for browsing or `ic_search_contacts` for people. No when-not-to-use or prerequisite info is 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, openWorldHint, idempotentHint, and destructiveHint, so safety profile is clear. The description adds that it returns specific fields but does not elaborate on pagination behavior (e.g., ordering, total count, or rate limits).

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

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

The description is a single sentence that is efficient and front-loaded with the main action. It could be slightly improved by structuring the return fields list more formally, but it is already clear and 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 tool's simplicity, the description covers its core purpose and return values. An output schema exists to explain return format, so full completeness is not needed. Minor gaps: no mention of pagination defaults or limits.

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

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

Schema coverage is 100% with descriptions for both parameters. The description only mentions 'with pagination' - adds no meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it lists companies with pagination and specifies the returned fields (ID, name, website, employee count, custom attributes). It uses a specific verb-resource pair ('List companies') and distinguishes from sibling tools like ic_get_contact or ic_list_conversations.

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 is provided. The description does not mention when not to use it or point to sibling tools like ic_search_contacts for filtering.

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 return field details (conversation ID, participants, status, etc.) and pagination behavior, which are helpful but not extensive. 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 sentence that front-loads the action and return information. It is concise and effective, though it could be slightly more structured (e.g., bullet points for return fields).

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 presence of an output schema, the description appropriately lists key return fields without over-explaining. The tool is simple, and the description covers the essential use case of listing conversations with pagination.

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%; both parameters are clearly described in the schema. The description's mention of pagination adds context but no new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'conversations', and specifies it supports pagination and returns key fields. Among sibling tools like 'ic_get_conversation' (singular) and 'ic_list_companies', it is distinct and unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives, no exclusions, no prerequisites. It only states what it does, leaving the agent to infer usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that results include contact ID, name, email, and metadata, but does not specify query behavior (partial matching, pagination) or the nature of metadata. With strong annotations, the additional context is adequate but not rich.

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 consists of two concise sentences with no unnecessary words. The action and return values are front-loaded, making it efficient for an agent to parse.

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

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

Given the tool has an output schema, the description's mention of return fields is helpful. However, it omits that the result is a list of contacts, and does not address potential limits or ordering. For a simple search tool with one parameter, the completeness is good but could be slightly improved.

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

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

Schema has 100% coverage and the property description already states 'Search by email, name, or other field.' The tool description echoes this without adding new parameter semantics, such as valid formats or constraints. Baseline 3 is appropriate when the schema carries the full burden.

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 searches for contacts by name, email, or custom attributes, and lists the returned fields. It differentiates from the sibling tool ic_get_contact, which retrieves a single contact, by explicitly indicating a search operation.

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 indicates the tool is for searching contacts, which is distinct from the sibling ic_get_contact (single record retrieval). However, it does not explicitly state when not to use it or provide alternatives beyond the implicit distinction.

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, destructiveHint=false, etc. Description adds return field list and parameter effect, but no further behavioral traits. Adequate given annotation richness.

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

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

Two concise sentences: first states purpose and return fields, second gives usage guidance. No wasted words, front-loaded.

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

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

Fully sufficient for a read-only list tool with comprehensive annotations and one simple parameter. No missing context.

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

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

Schema covers the only parameter (include_inactive) with full description (100% coverage). Description does not add further meaning, so baseline 3 is appropriate.

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

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

Clearly states the verb 'list', resource 'subscriptions', and scope 'caller's active'. Also lists returned fields, distinguishing it from sibling tools like subscribe/unsubscribe.

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

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

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' No explicit when-not-to-use, but context is clear.

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

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

Discloses important behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, does not count against tool-call quota, and that feedback directly affects roadmap. 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?

Concise yet comprehensive; every sentence serves a purpose. Front-loaded with purpose, then usage, then constraints. 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?

All necessary context is provided: what to send, how to structure, constraints like rate limits and quota. Since there is no output schema, the description adequately covers input behavior.

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?

Adds value beyond the input schema by explaining each enum value in context and providing guidance on message length (1-2 sentences, max 2000 chars). Although schema coverage is 100%, the description enriches parameter understanding.

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

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

The description clearly states the tool's purpose: to send feedback (bug, feature, data_gap, praise) to the Pipeworx team. It distinguishes itself from sibling tools by focusing on feedback submission, not querying or managing data.

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

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

Explicitly specifies when to use each feedback type (bug for wrong/stale data, feature for missing tools, praise for positive experiences) and provides guidance on what to include (reference Pipeworx tools/packs, not end-user prompts). Also mentions rate limits and no quota impact.

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

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

Annotations already indicate readOnly, idempotent, non-destructive, and openWorld hints. The description adds context: it is self-aggregating, derived from CF analytics-engine, contains no PII, and has caching details (5min-1h depending on window). This provides useful behavioral transparency 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 a single paragraph that efficiently conveys purpose, use cases, and behavioral details without redundancy. Every sentence adds value, and the structure with numbered uses is 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?

Given that there is no output schema, the description should detail the return format. It mentions 'top tools, top packs, and total call volume' but does not specify the structure (e.g., list of objects, field names, ordering). This missing detail limits completeness for an agent selecting the tool.

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

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

The input schema has one parameter with an enum and description. The description adds value by explaining the semantic difference between windows: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema's brief 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 what the tool does: returns top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d). It uses specific verbs and resources, and the name 'trending' aligns with the purpose. It distinguishes itself from siblings by focusing on aggregate call volume rather than individual tool usage.

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 three explicit use cases: discovering hot data sources, confirming canonical tool choices, and aligning use cases with agent needs. It also mentions caching behavior. However, it does not provide explicit when-not-to-use guidance or compare directly to sibling tools like 'discover_tools', but the scenarios are sufficiently 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 indicate read-only, open-world, and idempotent behavior. The description adds rich context: it walks child markets, checks ordering, computes partition_check, performs fill_check against live CLOB depth, and details the semantic anchor and partition filter. 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 fairly long but well-structured, front-loading the requirement and then detailing each mode and sub-function. Every sentence adds value, though 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?

Given the tool's complexity (two modes, partition check, fill check) and lack of output schema, the description covers response structure, fill check logic, and references related tools. It is comprehensive 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 coverage is 100% with descriptions for both parameters. The description adds meaningful context beyond schema: provides example slugs, explains the behavioral difference between `event` and `topic`, and specifies the conditions for cross-event mode (Jaccard similarity).

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 via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and explains their specific purposes, making the tool's function unambiguous.

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

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

The description explicitly requires one of `event` or `topic`, warns that calling with no args fails, and provides recommendations for each mode. It also explains when not to trade based on fill check results and references the sibling `polymarket_fill_risk` for custom sizing.

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 confirm the tool is read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context: 1-hour KV-level caching keyed on knobs, the exclusion of Fed bets from ranking due to unreliable data, and the inclusion of a 24-hour move warning indicating the edge may already be priced in. 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 excessively long (over 600 words) with extensive technical details, model formulas, and specific constants. While structured into sections, the core purpose is buried in dense text. A more concise version would improve agent parsing.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, diagnostics, fed_candidates) and covers all parameters. It compensates for the missing schema by detailing field semantics and reasoning exclusions.

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 9 parameters, baseline 3. The description adds value by explaining the 'Tradeable-edge knobs' concept (min_liquidity, max_spread_pp), clarifying that min_edge_pp is net of slippage, and detailing min_partition_leg_kelly's role for basket trades. These enrich 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 that the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, specifically for the 'what should I bet on today' use case. It distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on Pipeworx data divergence rather than cross-platform 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 implies usage for discovering betting opportunities but does not explicitly contrast with sibling tools like 'polymarket_arbitrage' or provide when-not-to-use guidance. It lacks explicit context about when to prefer this tool over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial behavioral context: it reads daily snapshots, returns tracked/expired/snapshot_dates, specifies that decay numbers come from daily closes not intraday, and mentions the 60-day snapshot TTL. This exceeds annotation coverage.

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

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

The description is moderately long but efficiently packs information. It front-loads the core purpose and uses plain language. Every sentence adds value, though it could be slightly more structured with bullet points for the return fields.

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 return structure (tracked, expired, snapshot_dates with fields) and data sources. It also covers limits and edge cases, making it sufficiently complete for an agent to use 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%, so baseline is 3. The description repeats schema info (defaults, ranges) and adds context about response structure, but does not significantly augment parameter semantics beyond what the schema provides.

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

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

The description clearly states what the tool does: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges (which likely provides current edges) by focusing on historical tracking.

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 context for when to use the tool, e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades.' It explains limits and data sources, but does not explicitly mention alternative tools or when not to use it. The guidance is clear and actionable.

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

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

The description adds significant behavioral context beyond annotations: it explains that the tool walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, etc.), and in basket mode identifies thin legs and forced directional risk. This aligns with the readOnlyHint and idempotentHint 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?

The description is relatively long but well-structured with clear mode breakdowns and all-caps emphasis for key points. It is front-loaded with the core purpose and follows with detailed usage. While slightly verbose, every sentence serves a purpose, earning a high score with minor room for tighter phrasing.

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 absence of an output schema, the description comprehensively explains all return fields for both modes (metrics like fill price, slippage, etc.) and includes necessary warnings. It covers required parameters, defaults, and edge cases, making it fully informative 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?

With 100% schema description coverage, the description still adds value by clarifying parameter meanings across modes, such as how size_usd is interpreted differently for single-market (spend/target proceeds) versus basket (settlement notional per leg). Default values and ranges are also explained.

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: checking realizable vs. theoretical edge against live order-book depth. It specifies two modes (single-market and basket) and lists the specific metrics returned, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges by advising its use before acting on their signals.

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

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

The description explicitly states the requirement for either 'market' or 'event' parameter and explains both modes in detail. It provides clear guidance on when to use the tool (before arb signals or trades above ~$500) and warns against the risks of partial basket fills, offering excellent usage direction.

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 and idempotentHint, but the description adds significant behavioral context: the two modes, response structure (leg-by-leg prices, spreads), safety fields (compatibility_warning, temporal_alignment), and counters for skipped comparisons. No contradiction with annotations.

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

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

The description is detailed and well-structured with clear sections, but it is quite lengthy. Every sentence provides useful information, but it could be more concise without losing essential details.

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

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

Given the tool's complexity (cross-venue, multiple modes, safety checks) and lack of output schema, the description adequately covers return values and safety warnings. It explains temporal alignment and compatibility checks, ensuring the agent understands when spreads are meaningful.

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

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

The input schema already describes all three parameters with 100% coverage, but the description adds meaning by explaining the topic shortcut list, how explicit parameters override topic, and providing examples. This adds value beyond the schema.

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

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

The description clearly states that the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, and describes two distinct modes (topic shortcuts and explicit event tickers). It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue spread.

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 two modes and provides guidance on when each is appropriate (topic shortcuts for common macros vs explicit tickers for custom pairings). It also warns about compatibility issues and that pre-mapped topics may not be tradeable, but does not explicitly contrast with sibling tools.

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

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

Annotations already declare readOnlyHint and idempotentHint true. The description adds scoping to identifier (anonymous IP, BYO key hash, or account ID), which is valuable behavioral context 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?

Three sentences with no wasted words. The first sentence front-loads the primary purpose. Each subsequent sentence adds essential context: usage scenario, scoping, and pairing with sibling tools.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage context, scoping, and relationships to siblings. No gaps.

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

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

Schema coverage is 100% for the single optional key parameter. The description adds that omitting key lists all saved keys, which is meaningful semantic information beyond the schema's property description.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if key is omitted. It uses specific verbs ('retrieve', 'list') and explicitly distinguishes from sibling tools (remember, forget).

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

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

The description explains when to use ('to look up context the agent stored earlier') and pairs with remember/forget. It provides clear context but does not explicitly state when not to use, though the purpose is well-defined.

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 key behaviors beyond annotations (readOnlyHint, etc.): explains that each event carries specific fields, and setting mark_read:true flags events as read to affect subsequent calls. 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?

Three sentences with no wasted words. First sentence states purpose, second details return fields, third explains mark_read and alternative endpoint. 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?

Given rich annotations and full schema coverage, the description provides all necessary context: return fields, filter options, polling behavior, and alternative access method. No output schema, but return values are described adequately.

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

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

Schema covers all 5 parameters (100% coverage). The description adds value by clarifying the effect of mark_read ('so the next call only shows newer ones') and mentions filtering by type and since, going 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?

Clearly states 'Pull fired events from your subscription feed' and details what data is returned (source, citation_uri, raw event payload). Employs a specific verb ('Pull') and resource ('alerts') that distinguishes it from sibling tools like subscribe/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?

Provides context that polling works and mentions an alternative REST endpoint for scripts/dashboards. However, lacks explicit guidance on when not to use this tool compared to siblings.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description details internal behavior: fan-out to SEC EDGAR, GDELT→GNews fallback with conditions (rate-limited/5xx), USPTO soft-fail due to API sunset, and return structure (changes[] grouped by source, total_changes, 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 front-loaded with clear examples and uses efficient language. While it is comprehensive, it could slightly trim the example list without losing value. However, every sentence contributes to understanding.

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

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

Despite lacking an output schema, the description explicitly states the return format (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs) and covers all important aspects: sources, fallback behavior, parameter syntax, and alternative tool. 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 description adds critical meaning: explains `value` accepts ticker or CIK, `since` accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y') and recommends '30d'/'1m' for monitoring. `type` is confirmed as only 'company'.

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

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

Description starts with clear examples of queries ('What's new with X', 'latest on Y') and explicitly states it provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It distinguishes from the sibling 'entity_profile' by noting that tool is for static profiles.

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

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

The description gives explicit when-to-use guidance with example queries, and directly contrasts with 'entity_profile' for static profile needs, providing clear differentiation.

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 idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds valuable context: scoping by identifier, persistence differences between authenticated and anonymous users, and retention periods, which go beyond the structured fields.

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 with the core purpose front-loaded, but it contains some redundant phrasing ('across this conversation or across sessions' could be shortened). Still, it is efficient and avoids unnecessary fluff.

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

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

For a simple key-value store with two parameters and no output schema, the description covers usage context, retention behavior, and pairing with sibling tools. It lacks details on error handling or capacity limits, but is sufficient for effective 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 coverage is 100%, so baseline is 3. The description adds examples for keys (e.g., 'subject_property', 'target_ticker') and clarifies that value is any text, providing meaningful 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 uses specific verbs like 'save' and 'reuse later', clearly identifies the resource (data across sessions/conversations), and distinguishes from sibling tools 'recall' and 'forget' by mentioning them explicitly.

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

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

The description provides explicit guidance on when to use the tool ('when you discover something worth carrying forward') and pairs it with 'recall' and 'forget', but does not explicitly state when not to use it or alternative tools besides those two.

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 value by stating it cascades through several lookup endpoints internally and describes return formats for each type. 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 example queries, then stating clear purpose, supported types, and output details. Every sentence adds value, no wasted words.

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

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

Given no output schema, the description thoroughly explains return values for both entity types, including citation URIs. The tool's complexity is well covered.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning beyond the schema: explains the type parameter effects (company returns ticker+CIK+name, drug returns RxCUI+ingredient+brand) and gives examples for value, including auto-disambiguation for company.

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

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

The description clearly states the verb 'resolve' and resource 'entity', gives example queries, and specifies it returns canonical identifiers. It distinguishes from siblings by mentioning it replaces 2-3 manual 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It provides context for when to use but does not explicitly contrast with alternative tools like entity_profile or compare_entities.

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 behavioral detail: it probes each entity via ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. 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?

Three sentences, front-loaded with the core action, followed by use case example and output description. No redundant or filler content.

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

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

No output schema exists, but the description partially covers return structure (ranked list with score, confidence, signal density). It could benefit from clarifying ordering or handling ties, but overall it's sufficient for a comparison tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity is treated as the 'subject' for narrative purposes and the rest as competitors, which aids understanding 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 compares AI visibility across multiple entities using ai_visibility_check, ranks results, and identifies most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and implies when to use (comparing multiple entities). It does not explicitly state when not to use or alternatives, but the context strongly suggests it's for multi-entity comparisons.

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 fan-out behavior, partial failure handling (bundlephobia latency, sources_failed), and return fields. Annotations already indicate read-only, but the description adds valuable 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?

The description is thorough but slightly verbose; however, it is well-structured with front-loaded purpose and logical flow. Could tighten some phrases.

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

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

Despite no output schema, the description fully details return fields (summary, advisories, links, alternatives) and explains partial failures, providing complete context for an agent.

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

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

Schema coverage is 100%, and description enriches both parameters: package parameter notes scoped packages accepted; version parameter notes default behavior when omitted.

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 specifies it's a composite check for npm packages, aggregating data from deps.dev and bundlephobia, clearly distinguishing it from sibling tools which are mostly 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 states when to use: when an agent asks about safety, popularity, or size of an npm package. Also notes it's NPM-only and mentions alternatives for other ecosystems.

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

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

The description adds significant behavioral context beyond annotations: it specifies embeddings (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K with truncation flag), and the fact that it returns offsets. Annotations already indicate read-only, idempotent, non-destructive, and the description aligns with those.

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

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

The description is concise (two sentences) with no wasted words. Front-loaded with the core purpose and key differentiators, then technical details. Every sentence adds value.

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

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

Despite no output schema, the description fully explains the return (top-N passages with character offsets and similarity scores). It covers limitations (truncation cap), provides examples, and suggests integration with other tools. The description 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%, so baseline is 3. The description adds value by explaining the query format ('natural-language query'), the default for limit (5), and the character limit for text (200K). It also gives examples of queries, enriching the parameter meaning 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 uses specific verbs ('Semantic search INSIDE a fetched record') and resource ('a fetched record'), with clear examples (SEC 10-K, article, tool result). It distinguishes itself from sibling tools like ask_pipeworx_grounded by focusing on searching within an already fetched text.

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

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

The description explicitly states when to use the tool ('when the record is too big to cram into the prompt'), lists benefits (saves context, returns relevant passages with offsets for verification), and suggests pairing with ask_pipeworx_grounded. It provides clear context and alternatives.

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

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

Annotations indicate a write operation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds critical behavioral details: SMS rate limit (10/day), webhook secret handling (returned once), auto-disable after 10 failures, and account restrictions. This goes well 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 moderately long but well-structured with examples and bullet points. Every sentence adds value, though some redundancy (e.g., repeating delivery details) could be trimmed. Overall efficient for the complexity.

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

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

Despite no output schema, the description mentions 'Returns the new subscription id.' It covers all important aspects: types, params, delivery, account requirements, rate limits, and error conditions (auto-disable). An agent has sufficient information to use the tool correctly.

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

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

With 100% schema coverage, the description still adds significant value by providing concrete examples for each type (e.g., sec_8k with items, polymarket_edge with topic) and explaining delivery channel constraints (verified phone, email validation, webhook HTTPS requirements).

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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 prerequisites (Pipeworx OAuth account required) and examples for various subscription types, but does not explicitly state when not to use it versus alternatives. However, the context is clear enough for an agent.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds details about the output (category-bucketed examples) and usage patterns (full spread vs. topic focus), enhancing behavioral understanding without contradiction.

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

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

The description is front-loaded with key trigger phrases and structured with function, output, and usage instructions. While slightly verbose, it efficiently conveys all necessary information 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?

Complete coverage for a simple tool with one optional parameter: explains purpose, when to use, arguments, and output format (category-bucketed example questions). No output schema needed as description suffices.

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 includes parameter description. The description adds context that omitting topic gives full spread and lists focus areas, providing slight semantic 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 identifies the tool as the onboarding entry point for Pipeworx, listing trigger phrases and explicitly stating it returns category-bucketed example questions with tool+argument shapes, which distinguishes it from siblings.

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

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

Explicitly advises to use this first when unfamiliar with Pipeworx, to learn how to call meta-tools, and specifies when to pass a topic. Provides clear context for its use relative to other tools.

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

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

Annotations already indicate non-read-only, non-destructive, and idempotent behavior. The description adds valuable behavioral detail: the row is deactivated (not deleted) and historical events remain accessible via 'recent_alerts', 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?

Extremely concise: two sentences with no unnecessary words. The use of dashes for key points improves readability. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers the action, ownership constraint, and the side effect (soft deactivation with historical preservation). It references a sibling tool ('recent_alerts') for completeness. Minor gap: no mention of idempotency, but annotations handle that.

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 well-described parameter (id as uuid from subscribe). The description does not add new semantic meaning beyond 'by id', so it meets 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 clearly states the action (cancel/unsubscribe) and resource (subscription by id), and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying the cancellation action.

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

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

Provides explicit usage context: ownership enforcement (only cancel own subscriptions) and behavioral nuance (deactivation vs deletion). While it doesn't list when not to use, the context is sufficient for correct invocation.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant value by detailing the return format (verdict types, extracted data, citation, delta) and explaining it replaces multiple sequential calls, which aids in understanding behavior.

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

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

The description is one well-structured paragraph that is front-loaded with trigger phrases and purpose. Every sentence adds value, covering usage, scope, output, and efficiency benefits without redundancy.

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

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

Given the simple one-parameter tool, the description is complete: it covers what, when, how, and what to expect in return. No output schema needed as the return types are described in text.

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

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

The single parameter 'claim' is well-described in the schema (100% coverage). The tool description adds extra context with examples and domain-specific guidance, exceeding 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 defines the tool as a natural-language claim verification tool against authoritative sources, with specific examples and domain scope (company-financial claims). It distinguishes itself from sibling tools by its focused purpose.

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

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

The description states when to use ('whenever the agent needs to check factual correctness') and specifies the supported domain. It does not explicitly state when not to use, but the domain limitation is clear.

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