Gong

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds context about cost (free vs BYO Anthropic key), how the key is passed, and the return format per model. It does not discuss rate limits or potential delays, but overall provides useful behavioral context beyond annotations.

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

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

The description is two sentences with no fluff. The first sentence captures the core purpose and scoring, the second adds key details on models and return format. Every sentence is informative.

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

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

Given no output schema, the description sufficiently explains the return structure (per-model and combined view). It covers required parameter, optional parameters, and use cases. It does not mention any limits on number of models or concurrency, but is otherwise complete for a probe 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?

Input schema has 100% description coverage, so the schema already documents each parameter. The description adds value by clarifying default model behavior, the role of '_apiKey', and the disambiguation purpose of 'context'. This goes beyond the schema.

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

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

The description clearly states it 'probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This distinguishes it from sibling tools like 'entity_profile' or 'scan_competitor_ai_presence' by focusing on cross-model visibility scoring.

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

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

The description explicitly says 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring,' providing clear use cases. It also explains the default model and when an API key is needed. However, it does not contrast with similar tools like 'scan_competitor_ai_presence' or state when not to use it.

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

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

Annotations already declare safe, idempotent, readonly behavior. Description adds that it routes across 3,751 tools and returns pipeworx:// citations, providing useful operational context beyond annotations.

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

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

Well-structured with a strong opening directive, list of domains, explanation of routing, usage cues, and examples. Slightly verbose but each sentence contributes 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?

No output schema, but description explains it returns structured answers with stable citation URIs. Covers input, routing, and output format comprehensively for a tool with 6 param aliases and wide domain coverage.

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% of parameters (all aliases for 'question'), so description inherently adds little beyond schema. It clarifies that the parameter accepts natural language and provides usage examples, maintaining baseline adequacy.

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

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

Description clearly states it routes questions to authoritative structured data sources with citations, lists many specific domains (SEC filings, FDA, FRED/BLS, etc.), and contrasts with web search. Siblings like ask_pipeworx_grounded exist but are not differentiated, yet the description is still highly specific.

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

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

Explicitly says to prefer over web search for factual/structured questions, provides trigger phrases ('what is', 'look up', etc.), and gives concrete examples. Does not discuss when to avoid or contrast with ask_pipeworx_grounded, but overall strong guidance.

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

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

The description adds significant behavioral context beyond annotations: it explains the hallucination-resistant mechanism, the refusal reasons (not_in_source, no_tool_match, etc.), and the exact return format. It aligns with annotations (readOnly, openWorld) and does not contradict them.

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 yet comprehensive, front-loading the purpose and then detailing behavior, output format, and usage guidelines. Every sentence adds value without redundancy. It is well-structured for an agent to quickly understand.

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 documents the return JSON with all fields and refusal reasons. It covers behavior, cost, and use cases. Given the complexity of the tool, it provides complete context for agent decision-making.

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

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

Input schema describes 'question' and aliases with 100% coverage. The description adds context about the type of questions suitable (high-stakes, factual) and the refusal behavior, which guides parameter value choice. While not explaining syntax, it adds meaningful usage context.

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

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

The description clearly states the tool is a hallucination-resistant answer mode for high-stakes reads. It explains the same routing as ask_pipeworx but with extra extraction step, and explicitly distinguishes from the sibling tool by mentioning cost 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?

It provides explicit guidance on when to use: 'Use whenever an answer will be quoted, cited, or acted on' and lists domains like financial verdicts, legal claims. It also tells when not to use: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost.

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

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

Annotations declare read-only, idempotent, non-destructive behavior. The description far exceeds this by detailing fan-out patterns per category, response shapes (market, analysis, evidence), safety short-circuits (low_confidence_match, market_closed_or_inactive), spread warnings, resolution-rule risk parsing, and news fallback handling. All relevant behavioral traits are disclosed.

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 overly long for a typical tool definition. It uses clear section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) but is not front-loaded; critical usage context appears early but detailed edge cases delay key information. Concision could be improved by summarizing behavioral nuances.

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 covers input, behavior, output shapes, error conditions (cancellation rules, liquidity warnings), and edge cases (closed markets, low-confidence matches). This compensates for the schema gap and provides complete guidance for an AI agent.

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

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

Schema coverage is 100% and description enriches each parameter: market format (slug, URL, question), depth enum (quick vs thorough with default), include_raw with size implications. Examples illustrate usage. The description adds meaning beyond the schema alone.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies input types (slug, URL, question text) and distinguishes from specialized siblings like polymarket_edges or polymarket_arbitrage. The verb 'research' and resource 'Polymarket bet' are explicit.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and details blocking conditions (low-confidence matches, closed markets). However, it does not directly compare with sibling tools or state when to avoid using this tool.

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

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

Adds significant behavioral detail beyond annotations: explains data sources (SEC EDGAR for companies, FAERS for drugs), handles off-calendar fiscal years, results sorted by primary metric, returns paired data with citation URIs. No contradiction with readOnlyHint, openWorldHint, idempotentHint, destructiveHint.

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

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

Description is moderate length and front-loaded with trigger phrases and purpose. Each sentence contributes useful information (trigger phrases, comparison type, data sources, entity count, result format, performance claim). Minor redundancy in examples but overall efficient.

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

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

Given tool complexity (two entity types, multiple data sources, comparison context), description covers: what it does, when to use, data sources, sorting behavior, output format (paired data + citation URIs), and fiscal year handling. No output schema, but description provides sufficient return 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?

Both parameters have schema descriptions (100% coverage), but the description enriches them: for 'type', elaborates on data pulled per enum value; for 'values', gives concrete examples (tickers/CIKs for companies, drug names) and clarifies constraints. Adds 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?

Description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific verb phrases like 'Compare X and Y', 'X vs Y', etc. It distinguishes from sequential single-pack lookups and specifies data sources for each entity type, making purpose unambiguous.

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

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

Explicitly instructs to prefer this tool over sequential single-pack lookups when comparing entities and claims it replaces 8–15 sequential calls. Provides trigger examples. Does not explicitly name sibling alternatives but implies differentiation from 'entity_profile' which does single lookups.

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 show readOnly, openWorld, idempotent, non-destructive. Description adds substantial context: grounded answers with verbatim evidence, confidence, source, timestamps, stable citations, explicit gaps for unanswered facets, and pre-verified facts. Also notes parallelism and expected response time (15-60s). 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 a single dense paragraph with no wasted sentences. Every sentence adds unique information. It is well front-loaded with the main purpose. Slightly verbose in enumerating all features, but remains efficient. Could potentially be broken into bullet points for easier 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 return value: a structured findings packet with verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, and explicit gaps[]. It also covers prerequisites (account, paid plan for depth) and performance (parallel, 15-60s). All relevant aspects are addressed.

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 parameters with descriptions. The description adds value by explaining the enumeration values for depth (quick=3, standard=5, thorough=8) and linking 'thorough' to paid plans. It also clarifies that question should be natural language and can be broad/multi-part. This extends schema information.

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

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

The description clearly states the tool does 'grounded multi-source research in ONE call' and explains how it decomposes questions into sub-questions and routes them in parallel to 3,751 tools across 886 sources. It differentiates from sibling ask_pipeworx by contrasting multi-part vs single lookups.

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

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

Explicitly advises use for broad or multi-part questions and recommends ask_pipeworx for single lookups. Also mentions account requirements and paid plan for 'thorough' depth.

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

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

The description explains that the tool is read-only (consistent with readOnlyHint=true) and enriches annotations by stating it returns 'full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed,' adding behavioral detail beyond annotations.

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

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

The description is two concise sentences, front-loaded with the core purpose, uses a list of examples seamlessly, and contains no redundant or superfluous information.

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

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

Given no output schema, the description fully explains what the tool returns (tool names, descriptions, full schemas) and why it's useful (ready to call), making it complete for a tool discovery function.

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

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

Schema coverage is 100%, and the description adds value by listing aliases for the query parameter (task, q, description, search) and reinforcing its natural language usage, going 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 'Find tools by describing the data or task' and enumerates specific domains (SEC filings, financials, etc.), making the tool's unique purpose highly specific and distinguishable from siblings like deep_research or entity_profile.

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

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

The description explicitly instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing precise when-to-use guidance and implying when not to use it (when target tool is known).

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds significant behavioral context: it fans out across multiple sources, explains the patents component will soft-fail, and details the return fields (CIK, filings, fundamentals, etc.). No contradictions with annotations.

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

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

The description is detailed but every sentence contributes value. It front-loads with example queries and the key preference instruction. It could be slightly more structured (e.g., bullet points) but remains clear 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 the tool's complexity (multiple data sources, two parameters, no output schema), the description comprehensively covers input requirements, behavior (fan-out, soft-fail), limitations (names not supported, patents sunset), and expected outputs. It leaves no critical gaps for an agent.

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

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

Schema coverage is 100% with both parameters described. The description reaffirms the parameter constraints (type must be 'company', value must be ticker or zero-padded CIK) and adds context that names are not supported. It also notes future support for person/place. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: providing a full cross-source profile of a US public company. It uses specific verbs like 'profile' and gives numerous examples (e.g., 'tell me about X', 'research Acme'). It distinguishes itself from sibling tools by advising preference over chaining single-source 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?

Explicit guidance on when to use: when the user asks for a holistic view of a company. It warns against using names directly and directs to resolve_entity first. It also clarifies that patents will soft-fail, setting expectations.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds 'Delete' which is consistent but does not provide additional behavioral context beyond what the annotations convey.

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

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

Two efficient sentences with front-loaded action, 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?

With one parameter and no output schema, the description fully covers purpose, usage, and related tools, making it complete for this simple tool.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description does not add extra meaning beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, distinguishing it from siblings 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?

Explicitly states when to use the tool ('When context is stale, the task is done, or you want to clear sensitive data') and pairs it with related tools ('remember and recall').

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds that it fetches the page and extracts metadata, which is useful beyond the 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?

Two concise sentences that front-load the purpose and include relevant technical details. No wasted words.

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

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

Given the tool's simplicity, good annotations, and no output schema, the description fully covers what the agent needs: purpose, behavior, output format, and use cases. It is complete.

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

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

Schema coverage is 100% with clear descriptions for both required and optional parameters. The description doesn't add significant value beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for any URL, targeting AI crawlers. It specifies the output format and use cases, distinguishing it from sibling tools that have different purposes.

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 three explicit use cases (client indexing, personal project, competitor audit) but does not explicitly state when not to use 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, destructiveHint=false, and idempotentHint=true, indicating a safe, read-only operation. The description adds value by listing specific returned data categories (participants, duration, metadata, engagement metrics, key moments), which is not present in annotations. No behavioral traits beyond what annotations cover are disclosed, but the description enriches the tool's context.

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

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

The description consists of two concise sentences with no superfluous text. The key action ('Get full details') is front-loaded, and the return items are listed immediately. Every sentence earns its place.

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

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

The tool has a single parameter, the input schema is complete, and annotations cover safety. The description lists return categories, and since an output schema exists (context signals), the description need not explain exact output structure. The combination is sufficient for an agent 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?

The input schema covers the single parameter 'callId' with 100% description coverage, stating 'The Gong call ID'. The description does not add additional meaning beyond 'by ID'. With high schema coverage, baseline score is 3, and the description provides no extra parameter semantics.

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 'Get full details for a specific call by ID', specifying the verb ('get'), resource ('call'), and unique identifier ('by ID'). It distinguishes this from sibling tools like gong_list_calls (list all) and gong_get_transcript (get transcript) by focusing on full call details.

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 implicitly indicates usage when a call ID is known and full details are needed. While not explicitly listing alternatives or exclusions, the context from sibling tool names (e.g., gong_get_transcript for transcript, gong_list_calls for listing) provides clear differentiation. No explicit 'when not to use' is given, but the purpose is 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 already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. Description adds no extra behavioral context beyond the verb 'retrieve.' Minimal value added over annotations.

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

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

Two sentences, front-loaded with purpose, no redundant words. Every sentence serves a distinct function.

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 a simple tool with one parameter and an existing output schema, the description fully explains what is retrieved and when to use it. No gaps.

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

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

Schema coverage is 100% with a clear parameter description. The description does not add additional meaning about the callId parameter.

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

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

Description clearly states the tool retrieves a full transcript with speaker names, timestamps, and dialogue. It explicitly distinguishes from sibling 'gong_get_call' by positioning as a follow-up for deeper analysis.

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

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

Gives explicit context 'Use after gong_get_call to analyze specific conversations,' establishing a clear workflow. Does not list alternatives but provides sufficient directional guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds behavioral details: returns specific fields (IDs, dates, participants, duration, engagement metrics) and supports pagination. No contradictions.

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

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

Two succinct sentences: first states purpose, second lists return fields and pagination. Every sentence adds value, front-loaded information, no wasted words.

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

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

Given the input schema (3 optional params, all described), annotations covering safety, and an existing output schema, the description is complete. It mentions return fields and pagination, which is sufficient 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 the schema already documents all parameters. The description mentions 'optional date filtering' and 'pagination' but does not add new parameter-specific semantics 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 'recorded calls from your workspace', specifies optional date filtering, and enumerates return fields. It effectively distinguishes from sibling tools like gong_get_call and gong_search_calls by focusing on listing all calls with pagination.

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 tool's capability (list calls with date filtering and pagination) but does not explicitly contrast with alternatives like gong_search_calls or provide when-not-to-use guidance. The usage context is implied but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the behavioral safety profile. The description adds no new behavioral traits beyond confirming it is a listing operation, which provides minimal additional value.

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

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

Two sentences with no unnecessary words. The first sentence states the tool's action, the second enumerates the returned information. Every word earns its place.

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

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

For a simple, parameterless list tool with an output schema, the description adequately describes the purpose and return fields. It does not cover edge cases (e.g., empty workspace) or authentication, but these are minor given the tool's simplicity and the annotations.

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

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

The input schema has zero parameters, so the description does not need to explain parameter usage. It adds value by listing the output fields (names, IDs, etc.), which is not present in the schema. Baseline for zero parameters is 4, and the description meets that.

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 'all users in your workspace'. It also specifies the returned fields (names, IDs, emails, roles, activity status). This distinguishes it from sibling Gong tools like gong_list_calls or gong_get_transcript.

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 when user information is needed, but does not explicitly state when to use or not use this tool, nor does it mention alternative tools for different user queries. The context is straightforward for a list operation, but lacks exclusion or preference guidance.

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

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

Discloses that results are 'ranked by relevance', adding behavioral context beyond the annotations (which already indicate read-only, idempotent, non-destructive). No contradictions with annotations, and description adds value.

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

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

Two sentences with no unnecessary words. The first sentence states the action, the second describes the return format. Efficient and front-loaded.

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

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

Given the simple search functionality, one required parameter, comprehensive annotations, and existence of an output schema, the description provides all necessary context for an agent 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?

Schema coverage is 100%, so baseline is 3. The description provides additional example values matching the schema examples, but does not add new semantic information beyond what the schema already specifies.

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

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

The description uses the specific verb 'Search' and resource 'calls', clearly indicating the tool's function. It distinguishes from sibling tools like gong_list_calls (listing) and gong_get_call (retrieving a specific call) by focusing on keyword-based search.

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 examples of when to use (e.g., searching for 'pricing', 'objection'), which helps agents understand context. Does not explicitly state when not to use or mention alternatives, but the examples imply typical search scenarios.

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; description adds return field details and default scope of active subscriptions.

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, no redundancy, front-loaded with purpose and output.

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?

Sufficient for a simple list tool: states what is returned and when to use, despite no output schema.

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

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

Schema coverage is 100%, so description adds no extra meaning beyond what's in 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?

Clearly states the action (list) and resource (subscriptions), specifies returned fields, and distinguishes from subscribe/unsubscribe 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 tells when to use: to review monitoring before adding more or to find an id to cancel.

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

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

Annotations provide no behavioral hints, so description carries full burden. It discloses rate limit (5 per day), that it's free and doesn't count against quota, and that the team reads daily and impacts roadmap. 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?

A single paragraph that is dense but not verbose. First sentence states purpose, then conditions, then content guidance, then operational details. Every sentence adds value, nothing wasted.

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 simplicity of the tool (feedback submission with clear parameters and no output schema needed), the description covers all necessary aspects: what, when, how, limitations. 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 covers all parameters with detailed descriptions (100% coverage). Description adds contextual guidance on how to describe issues (in terms of Pipeworx tools/packs) and reinforces usage of enum values, but does not significantly augment what the schema already provides.

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

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

Clearly states it is for reporting bugs, missing features, data gaps, or praise to the Pipeworx team. Uses specific verbs like 'tell', 'describe', and distinguishes from any sibling tools (none serve this 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?

Explicitly when to use each type: bug for wrong data, feature for missing tools, data_gap for missing data, praise for positive experiences. Also advises against pasting end-user prompts and gives examples.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable context: data source (CF analytics-engine), no PII, caching details (5min-1h depending on window). No contradiction.

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

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

Description is well-structured with bullet points, front-loaded with the main output and three clear use cases. No unnecessary words; every sentence adds value.

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

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

Given no output schema, the description covers what is returned (top tools, top packs, total call volume), behavior (caching, no PII), and window semantics. Could mention limits or pagination, but sufficiently complete for a simple read 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?

Only one parameter (window) with enum and schema description. Tool description adds semantic nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Schema coverage 100%, but description adds interpretation.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window' with three specific use cases. It distinguishes itself from siblings like discover_tools by focusing on trending data.

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

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

Explicitly lists three situations for use (discovering hot data sources, confirming popular tool, checking use case alignment). Does not mention when not to use or alternatives, but 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?

The description adds extensive behavioral context beyond annotations: it explains the checks performed (monotonicity, partition sum), semantic anchor (Jaccard similarity), partition filter, fill check with live CLOB depth, and output structure. It does not contradict annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is detailed and well-structured, with clear sections for each mode and important notes capitalized. It front-loads the requirement. While somewhat verbose, the complexity of the tool justifies the length. It could be slightly more concise but remains 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 no output schema, the description fully explains the return value (opportunities array, partition_check object, fill_check details). It covers inputs, modes, edge cases (Jaccard similarity, placeholder filter, fill check), and references related tools. It is comprehensive for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the difference between event and topic modes, provides example slugs, describes what happens in each mode (walks child markets, search across platform), and details the resulting logic (partition_check, fill_check). This greatly enhances understanding of how parameters affect behavior.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, and distinguishes between single-event and cross-event modes (event vs topic). It differentiates from siblings by mentioning polymarket_fill_risk for custom sizing.

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 against calling with no args, recommends event for specific markets and topic for cross-event scanning, and provides examples. It also advises not to trade when realizable_edge_pp ≤ 0. However, it does not fully contrast with all 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, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral details beyond this: model family calculations (e.g., crypto_price lognormal barrier, news_momentum GDELT), edge computation (edge_pp_net after slippage, Kelly fractions), response segmentation (by_segment), diagnostics for empty segments, caching (1h KV-level), and Fed bets exclusion rationale. No contradictions with annotations.

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

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

The description is very lengthy (multiple paragraphs) and densely packed with technical model details. While well-structured with sections, it could be more concise for an AI agent. Every sentence provides value, but the verbosity reduces readability. Front-loading the purpose is good, but the model details might overwhelm.

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 high complexity (9 parameters, no output schema), the description is exceptionally complete. It covers all aspects: model families, response structure (by_segment, diagnostics), edge calculation, filters, caching, and Fed bets nuance. Without an output schema, the description compensates by detailing the top-level response fields and what callers can expect.

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. However, the description adds significant value by explaining each parameter's purpose, recommended values, and edge cases. For example, min_kelly: 'Skips opportunities that are too small to bet sensibly'; slippage_pp: explains zero fees but bid/ask spread; min_partition_leg_kelly: clarifies why partition arbs have parent-level kelly=0 and how per-leg Kelly works. This goes well beyond the schema descriptions.

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

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

The description clearly states the verb (scan), resource (top Polymarket markets), and unique value (opportunities where Pipeworx data disagrees with market price). It distinguishes itself from siblings like polymarket_arbitrage by explaining its model-driven and structural arbitrage approach, and explicitly says 'Built for what should I bet on today'.

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 tool's primary use case (discovering opportunities without paging) and provides guidance on tradeable-edge knobs (min_liquidity, max_spread_pp) and when to use filters. However, it does not explicitly mention when not to use it or compare with specific sibling alternatives like polymarket_arbitrage or polymarket_edge_tracker, which would clarify selection.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context: limits on history depth, data source (daily closes, not intraday), and explanation of snapshot gaps. There is no contradiction with annotations.

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

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

The description is well-structured with distinct sections: purpose, args, response format, and limits. It is front-loaded with the key question and every sentence adds value. Despite its length, it is concise for the complexity of the tool.

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

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

With no output schema, the description fully explains the return values (tracked[], expired[], snapshot_dates[]), their fields, and behavior (e.g., sign convention, gaps). It also covers data source and limitations, leaving little ambiguity for an AI agent.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description repeats the parameter details but does not add significant new meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It explicitly answers the question 'how long has this edge existed and is it shrinking?', and distinguishes it from siblings (e.g., polymarket_edges) by its time-series focus.

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 implicitly indicates when to use (to assess edge longevity and decay) and provides limits (e.g., history depth, gaps in snapshots). However, it does not explicitly mention alternatives or when not to use, which would push it to a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive hint. Description adds substantial context: it walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), clamps size_usd, and warns about forced directional risk in basket mode. These behavioral details go 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 fairly long but well-structured with uppercase section headers (SINGLE-MARKET, BASKET) and clear bullet points for outputs. It is front-loaded with the core purpose. While some sentences are dense, every part earns its place given the tool's complexity. Could be slightly tighter but still reasonably 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?

For a complex tool with two modes and no output schema, the description lists all key return fields for both modes (e.g., top_of_book, vwap_fill_price, verdict for single; capture_ratio, profit_usd, thin_legs for basket). It also explains the 'forced_directional_risk' concept. This adequately covers what the tool returns, though an output schema would reduce the burden further.

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%, baseline 3. Description adds value by explaining that size_usd meaning differs per mode (max spend vs target proceeds for single-market, settlement notional for basket), that default side for basket is auto-determined from partition sum, and that market and event are mutually exclusive. This clarifies semantics beyond the schema.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific outputs and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by indicating when to use this tool before those.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable on thin books, partial fills create directional risk). Provides clear context for when to use each mode (single-market vs basket) and default behaviors.

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 readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds depth by explaining the compatibility warning conditions, temporal alignment, and skipped cross-type/subtype counters, which go beyond the annotations. No contradiction.

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

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

The description is relatively long (~300 words) but well-structured with clear sections (modes, response, safety fields). Every sentence adds useful information, though minor trimming 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?

Without an output schema, the description thoroughly covers return values (leg-by-leg prices, matched spreads, compatibility_warning, temporal_alignment, skipped counters). Given the tool's complexity, this is highly complete.

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

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

Schema coverage is 100% with descriptions for each parameter, but the tool description adds significant meaning: how topic maps to events, how explicit overrides work, and the context of pre-mapped shortcuts. This adds value beyond the schema alone.

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

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

The description clearly defines the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question. It uses specific verbs ('spread') and resources ('cross-venue'), and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on two venues.

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

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

The description explicitly explains two modes (topic shortcuts vs explicit pairing) and provides detailed guidance on when not to use: compatibility_warning cases, temporal alignment issues, and the note that most pre-mapped topics are not tradeable. This clearly sets expectations.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. Description adds listing behavior on omitted key, identifier scoping, and pairing with remember/forget, which are useful beyond annotations.

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

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

Three sentences, each adding value: main action, use cases, scope and pairing. No fluff, 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?

No output schema exists; description does not mention return format (e.g., value itself vs. array of keys when listing). While annotations cover read-only nature, behavior description is slightly incomplete for advanced 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 describes the single 'key' parameter. Description adds that omitting it lists all keys, and provides examples. 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?

Clearly states the tool retrieves a value saved via 'remember' or lists all keys when no key argument is provided. Specific verb-resource pairs (retrieve value, list keys) and mentions sibling tools (remember, forget) for distinction.

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 to use for looking up context without re-deriving it, and mentions scope per identifier. Does not explicitly state when not to use, but pairing with remember/forget implies alternatives.

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

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

The description goes beyond annotations by explaining the mark_read parameter's side effect (flags events as read, affecting subsequent calls). This adds transparency for a mutating action despite readOnlyHint=true. No contradictions; the description is honest and clear.

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 (5-6 sentences), front-loaded with the primary action, and every sentence adds meaningful information (parameter details, polling advice, alternative access). No redundancy or filler.

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

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

Given no output schema, the description adequately explains return values (source, citation_uri, payload) and behavior (mark_read effect). It covers all parameters and use cases for a read-alert tool, making it self-sufficient.

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

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

All 5 parameters have descriptions in the schema (100% coverage). The description adds value by explaining the interplay between mark_read and unread_only, and clarifying the default limit. It provides usage nuances not fully captured in 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 action ('Pull fired events'), the resource ('subscription feed'), and the returned data ('most recent alerts' with source, citation_uri, and raw payload). It distinguishes itself from sibling tools by focusing on reading alerts, not managing subscriptions.

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

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

The description provides usage context: polling is fine, filtering by type and since, and marking as read. It mentions an alternative HTTP endpoint for scripts/dashboards, but does not explicitly compare to sibling tools or state when not to use it.

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

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

Discloses behavior beyond annotations: fans out to multiple sources with fallback logic (GDELT→GNews), USPTO sunset status, and return structure. No contradiction with annotations.

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

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

Description is well-structured and front-loaded with example queries, but could be slightly more concise. However, 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?

Comprehensive for a complex tool with no output schema: covers purpose, sources, fallback, parameter formats, return structure, and future behavior. Adequately prepares the agent for 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?

Even though schema coverage is 100%, description adds valuable context: explains 'since' formats with examples and recommends default, clarifies 'value' accepts ticker or CIK, and notes 'type' only supports '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 tool returns a change feed for a company in a specified time window, with example queries ('What's new with X'). It distinguishes from sibling tool 'entity_profile' by explicitly 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?

Provides explicit guidance on when to use (queries for recent changes), date format usage, and when to use alternative 'entity_profile' for static profile. Also suggests default '30d' for typical monitoring.

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 scoping by identifier and persistence differences (persistent for authenticated, 24h for anonymous) beyond annotations.

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

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

Four focused sentences, front-loaded with purpose, efficient and clear.

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

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

Complete for a storage tool without output schema: explains scope, persistence, and pairing without gaps.

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

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

Schema coverage is 100% and description does not add extra meaning 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?

States specific verb 'save' and resource 'data', distinguishes from sibling tools recall and forget.

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

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

Explicit when to use: 'when you discover something worth carrying forward' plus examples and pairing with recall/forget.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond annotations: it mentions internal cascading through multiple lookup endpoints, replaces 2-3 manual lookups, and notes the auto-disambiguation feature. No contradiction with annotations.

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

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

The description is a single paragraph but well-structured: front-loaded with examples, followed by purpose, usage guidance, and type-specific details. It is concise with no wasted words, though bullet points could improve readability slightly.

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

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

For a tool with 2 required parameters and no output schema, the description is fairly complete. It explains what each type returns, including citation URIs. However, missing are potential error cases or failure scenarios (e.g., unrecognized entity). Still, it provides adequate context for the 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%, but the description adds significant meaning: it explains what the tool returns per type (company: ticker, CIK, name, citation URI; drug: RxCUI, ingredient, brand, citation). It also clarifies that value can be various formats (ticker, CIK, name). This goes well beyond the minimal schema descriptions.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific examples like ticker, CIK, RxCUI. It distinguishes from siblings by emphasizing it's the first step when an ID is needed. The verb 'resolve' and resource 'entity' are specific 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 explicitly says 'Use FIRST whenever you have a name but need an ID.' It details supported types and what each returns. While it doesn't explicitly contrast with siblings like compare_entities or entity_profile, the guidance is clear enough for the agent to select this tool appropriately.

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, destructiveHint=false, so safety profile is clear. The description adds value by explaining the tool 'probes each entity... with ai_visibility_check' and returns a ranked list with score, confidence, signal density. This composition behavior is not in annotations.

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

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

Two sentences with a practical example. Every sentence adds value: the first defines the action and output, the second gives a real-world use case. No wasted words, front-loaded with the core purpose.

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

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

The tool has 4 parameters, no output schema, no nested objects. The description explains the return format (ranked list with score, confidence, signal density) and the internal composition with ai_visibility_check. The schema already constrains entities to 2-8. Could mention potential rate limits, but for a comparison tool this is sufficient.

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

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

Input schema has 100% description coverage, so baseline is 3. The description adds additional meaning: first entity is the 'subject' for narrative, models can be omitted for default, and context disambiguates common names. This extra context justifies a 4.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, ranks results, and surfaces most/least recognized. It gives a specific use case (competitive AI-marketing audits) and distinguishes from the sibling ai_visibility_check (single entity) and compare_entities (likely more general).

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 tool is 'useful for competitive AI-marketing audits' and provides an example question. It implies use when comparing multiple entities, but does not specify when not to use or explicitly mention alternatives like ai_visibility_check for single probes. However, the sibling list provides 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 indicate read-only, idempotent, safe behavior. The description adds valuable context about graceful degradation and potential timeouts (bundlephobia's first measurement can take 5-30s). 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 front-loaded with a summary then details. Though lengthy, every sentence adds necessary information. Slight redundancy could be trimmed but overall well-structured.

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

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

Given no output schema, the description fully enumerates all returned fields (summary block, advisories, links, alternative versions). Covers edge cases like partial failures and timeouts. 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 the description confirms the package parameter accepts scoped names and version defaults to latest. This adds minimal 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 it is a composite check for npm packages covering license, advisories, bundle size, etc. It distinguishes itself from sibling tools like entity_profile and other scanners by specifying the exact use case.

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

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

Explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also notes ecosystem limitations and alternatives for non-NPM packages.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description reveals internal mechanics: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flag, and output fields (passages with offsets and scores). No contradictions.

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

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

Two concise paragraphs: first explains core function and usage, second technical details and pairing. Every sentence is informative, no fluff. Well-structured and front-loaded.

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

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

Despite no output schema, the description fully covers inputs, behavior (algorithm, chunking, limits), output format (passages with offsets/scores), truncation handling, and integration with sibling tools. 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%, so parameters are already described. The description adds usage examples for the query parameter and clarifies the text max, which enhances understanding beyond the schema. A 4 is appropriate for adding real value.

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

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

The description clearly states 'Semantic search INSIDE a fetched record,' specifying the action and resource. It provides concrete examples (SEC 10-K, article) and distinguishes from siblings by focusing on already-retrieved text, not external search.

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 the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, giving clear usage context. Does not explicitly list when not to use, but the context is strong enough for an AI agent to infer appropriate scenarios.

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 states 'Returns the new subscription id', implying each call creates a new subscription, but the annotations declare idempotentHint=true, indicating the operation should be idempotent. This is a contradiction, violating the requirement to not contradict annotations.

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

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

The description is well-structured and front-loaded with the core action. It provides necessary details without excessive verbosity, though it could be slightly more concise.

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

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

Given the complexity of multiple subscription types and delivery channels, the description covers authentication, type-specific parameters, delivery options with limitations, and return value. It is sufficiently complete for an agent 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?

The input schema has 100% coverage, so baseline is 3. The description adds significant detail beyond the schema, including concrete examples for each subscription type's params and extra context for delivery channels (e.g., phone verification, rate limits, webhook signing and auto-disable).

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 'Create a proactive monitoring subscription to a live-data event stream', which is a specific verb+resource, and states it returns a new subscription ID. This clearly distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description explains when to use the tool (setting up proactive monitoring) and specifies a prerequisite (Pipeworx OAuth account). It lists supported types and delivery channels, aiding in selection, though it does not explicitly state when not to use or compare to 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. Description adds behavior: returns categorized example questions with tool arguments. Does not contradict annotations.

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

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

Well-structured with front-loaded purpose and clear instruction. Slightly verbose but effective.

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

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

Given simple schema (1 optional param) and rich annotations, the description fully covers what the tool does, when to use it, and what it returns.

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

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

Schema has 100% coverage with parameter description. Description adds context by explaining the effect of omitting vs. including topic, listing example values, and elaborating on its purpose.

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, specifying that it returns category-bucketed example questions with tool+argument shapes. It distinguishes from sibling tools by advising to use it first when unfamiliar with Pipeworx.

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

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

Explicitly states when to use ('Use this FIRST'), provides optional topic parameter to focus, and mentions learning about meta-tools. However, it lacks explicit 'when not to use' guidance.

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

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

The description goes beyond annotations by explaining that the row is deactivated (not deleted) and that historical events remain available. It also clarifies ownership enforcement, which annotations do not cover.

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

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

The description is concise with two sentences that convey all necessary information without redundancy. It is front-loaded with the main action.

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

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

Given the tool's simplicity (single parameter, no output schema), the description covers the essential aspects: action, ownership, effect on data, and historical preservation. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description does not add new meaning to the 'id' parameter beyond what the schema provides ('Subscription id (uuid) returned by subscribe'). The description does reinforce the source of the id, but this is implicit in 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 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 by stating ownership enforcement ('you can only cancel your own subscriptions'). It implicitly suggests when to use (when cancelling own subscription) but does not explicitly exclude cases or mention 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the return structure (verdict types, extracted form, actual value with citation, percent delta) and noting that it consolidates multiple sequential 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?

The description is a single paragraph that effectively front-loads the purpose and usage examples. It is concise but could be slightly more structured (e.g., bullet points for return values). Every sentence adds value.

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

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

Given no output schema, the description comprehensively explains the return values (verdict, structured form, actual value, citation, delta). It also covers scope and limitations (v1 supports company-financial claims). The one required parameter is thoroughly described.

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

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

Schema coverage is 100% with a description for the 'claim' parameter. The tool description reinforces the natural-language aspect with examples like "Apple's FY2024 revenue was $400 billion", adding context beyond the schema's 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 defines the tool as natural-language claim verification with specific examples like "Is it true that…" and "fact check". It explicitly distinguishes from siblings by noting it replaces 4-6 sequential calls, and specifies the domain (company-financial claims for public US companies).

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

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

The description states "Use whenever the agent needs to check whether something a user said is factually correct" and clearly limits scope to company-financial claims (revenue, net income, cash position) via SEC EDGAR. It could be improved by explicitly stating when not to use it (e.g., for non-financial claims).

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