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

The annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds valuable context beyond this by specifying the return data (plan, credits, payment method status) and the practical use case for credit verification, which helps the agent understand the tool's behavioral output and purpose. No contradiction with annotations exists.

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

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

The description is well-structured and front-loaded with the core purpose, followed by return details, usage guidance, and parameter explanation. Every sentence earns its place without redundancy, making it efficient and easy to parse.

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

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

Given the tool's low complexity (1 optional parameter), the presence of annotations (readOnlyHint) and an output schema (which handles return values), the description is complete. It covers purpose, usage, parameter semantics, and behavioral context adequately without needing to explain return values.

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 1 parameter with 0% description coverage, but the description compensates by explaining the api_key parameter's purpose (Disco API key), format hint ('disco_...'), and optionality condition (can use env var instead). This adds meaningful semantics beyond the bare 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 specific action ('Check your Disco account status') and resource ('Disco account'), and distinguishes it from siblings by focusing on account status verification rather than analysis, payment, or other operations. It explicitly mentions what information is returned (plan, credits, payment method status).

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

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

The description provides explicit guidance on when to use this tool ('to verify you have sufficient credits before running a private analysis'), which clearly differentiates it from sibling tools like discovery_analyze (for analysis) or discovery_purchase_credits (for buying credits). It establishes a clear prerequisite 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?

The description adds valuable behavioral context beyond annotations: it explains security architecture ('card details never touch Disco's servers'), clarifies the prerequisite tokenization step via Stripe's API, and mentions the optional API key with environment variable fallback. Annotations provide idempotentHint=true and destructiveHint=false, which the description doesn't contradict but supplements with practical implementation details.

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

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

The description is efficiently structured with zero waste: first sentence states purpose, second explains security architecture, third gives usage context, fourth provides alternative tool guidance, and the Args section clearly documents parameters. Every sentence earns its place with essential information.

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

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

Given the tool's complexity (payment integration with external dependencies), the description is complete: it covers purpose, security model, prerequisites, usage context, parameter semantics, and alternative workflows. With annotations covering idempotency and non-destructiveness, and an output schema presumably handling return values, no significant gaps remain.

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

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

With 0% schema description coverage, the description fully compensates by explaining both parameters: payment_method_id is described as 'Stripe payment method ID (pm_...) from Stripe's API' and api_key as 'Disco API key (disco_...). Optional if DISCOVERY_API_KEY env var is set.' This adds crucial semantic context about format, source, and optionality that the bare schema lacks.

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 specific action ('Attach a Stripe payment method') and target resource ('to your Disco account'), distinguishing it from siblings like discovery_purchase_credits or discovery_subscribe which involve using payment methods rather than attaching them. It explicitly mentions the purpose is required before purchasing credits or subscribing to a paid plan.

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

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

The description provides explicit when-to-use guidance: 'Required before purchasing credits or subscribing to a paid plan.' It also distinguishes from alternatives by explaining that tokenization must happen via Stripe's API first, not through this tool, and gives the specific Stripe API endpoint to use instead.

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 destructiveHint=true and idempotentHint=false, but the description adds valuable behavioral context beyond this: it explains this is a 'long-running operation' with immediate run_id return, mentions cost implications (public vs private runs), authentication requirements for private reports, and workflow dependencies (upload first, then poll). While it doesn't explicitly mention destructive behavior, it provides operational context that complements the annotations.

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

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

The description is well-structured with clear sections: purpose statement, behavioral context, usage guidelines, prerequisites, and parameter explanations. While comprehensive, some sentences could be more concise (e.g., the LLM explanation is verbose). The information is front-loaded with the core purpose first.

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 (12 parameters, destructive operation, long-running nature) and the presence of an output schema (which handles return values), the description provides excellent contextual completeness. It covers workflow dependencies, cost implications, authentication requirements, operational characteristics, and parameter semantics, making it sufficiently complete for an agent to use effectively.

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

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

With 0% schema description coverage, the description carries the full burden of parameter documentation. It provides meaningful context for most parameters: explains target_column purpose ('what drives it, beyond what's obvious'), file_ref dependency, analysis_depth meaning, visibility cost implications, and gives specific guidance for column_descriptions. However, it doesn't cover all 12 parameters equally well (e.g., author, source_url get minimal explanation).

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 with specific verbs ('Run Disco on tabular data to find novel, statistically validated patterns') and distinguishes it from alternatives by explicitly stating what it is NOT ('NOT another data analyst', 'Do NOT use this for summary statistics, visualization, or SQL queries'). It differentiates from siblings by explaining its unique discovery pipeline approach.

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

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

The description provides explicit guidance on when to use ('Use this when you need to go beyond answering questions about data and start finding things nobody thought to ask') and when not to use ('Do NOT use this for summary statistics, visualization, or SQL queries'). It also mentions prerequisites ('Call discovery_upload first') and alternatives ('Use discovery_status to poll and discovery_get_results to fetch completed results').

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 valuable behavioral context beyond the readOnlyHint annotation. It explains that this is a pre-check tool to avoid unexpected costs, describes the different visibility modes (public vs private), clarifies the LLM behavior difference between public and private runs, and mentions the API key fallback to environment variable. While the annotation covers safety, the description provides important operational context.

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

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

The description is well-structured and appropriately sized. It starts with the core purpose, then lists outputs, provides critical usage guidance, and details each parameter with meaningful explanations. While comprehensive, every sentence earns its place by adding necessary information for tool selection and invocation.

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 (7 parameters, cost estimation function) and the presence of an output schema, the description is complete. It explains the tool's role in the workflow, distinguishes it from siblings, provides parameter semantics that the schema lacks, and gives operational context. The output schema existence means the description doesn't need to detail return values.

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

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

With 0% schema description coverage, the description fully compensates by providing detailed semantic explanations for all 7 parameters. It explains what each parameter means (e.g., 'analysis_depth: Search depth (1=fast, higher=deeper)', 'use_llms: Slower and more expensive, but you get smarter pre-processing...'), specifies defaults, and clarifies optional vs required parameters with practical implications.

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

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

The description clearly states the tool's purpose: to estimate cost, time, and credit requirements before running an analysis. It specifies the exact outputs (credit cost, duration, credit sufficiency, free alternative existence) and distinguishes it from sibling tools by explicitly mentioning its relationship to discovery_analyze for private runs.

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 usage guidance: 'Always call this before discovery_analyze for private runs.' It also distinguishes between public (free) and private (costs credits) runs, and clarifies that LLMs only apply to private runs while public runs always use them. This gives clear when-to-use and when-not-to-use criteria.

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 annotations provide readOnlyHint=true, indicating a safe read operation. The description adds valuable context beyond this by detailing what the response includes (patterns, feature importance, summary, etc.) and the dashboard_urls object with links to interactive reports. It doesn't contradict annotations and enriches understanding of the tool's behavior and output structure.

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, starting with the core purpose, then detailing the response, usage guideline, and parameters. Every sentence adds value without redundancy, making it efficient and easy for an agent to parse quickly.

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 (fetching results of a data analysis run), the description is complete: it explains the purpose, output content, usage timing, and parameters. With annotations covering safety and an output schema presumably detailing the return structure, no critical gaps remain for effective agent 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?

With 0% schema description coverage, the description compensates by explaining both parameters: run_id ('The run ID returned by discovery_analyze') and api_key ('Optional if DISCOVERY_API_KEY env var is set'). It adds meaning beyond the bare schema, clarifying sources and optionality, though it could provide more detail on format or constraints.

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 specific action ('Fetch the full results') and resource ('a completed Disco run'), distinguishing it from siblings like discovery_status (which checks status) or discovery_analyze (which initiates analysis). It precisely defines what the tool does without being vague or tautological.

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

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

The description explicitly states when to use this tool: 'Only call this after discovery_status returns "completed".' It provides a clear prerequisite and distinguishes it from alternatives by specifying the required state of the Disco run, guiding the agent on proper sequencing.

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 annotation readOnlyHint=true already indicates a safe read operation, but the description adds valuable context by stating 'No authentication required' and specifying that it returns 'all available subscription tiers with credit allowances and pricing.' This enhances transparency beyond the annotation, though it doesn't detail rate limits or error behaviors.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by authentication and usage context in two additional sentences. Each sentence adds value without redundancy, making it efficient and well-structured for quick understanding.

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

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

Given the tool's simplicity (0 parameters, read-only, with output schema), the description is complete. It covers purpose, authentication, usage guidance, and output content, which is sufficient for an AI agent to select and invoke this tool correctly without needing further explanation of return values due to the 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?

The input schema has 0 parameters with 100% coverage, so the schema fully documents the lack of inputs. The description doesn't need to add parameter details, but it implicitly confirms no inputs are required by focusing on the output, which is appropriate. A baseline of 4 is given as it compensates adequately for the zero-parameter case.

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 resource 'available Disco plans with pricing,' distinguishing it from siblings like discovery_purchase_credits or discovery_subscribe that involve transactions. It specifies the scope as 'all available subscription tiers with credit allowances and pricing,' making the purpose explicit and distinct.

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

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

The description explicitly states 'Use this to help users choose a plan,' providing clear context for when to invoke this tool. It also mentions 'No authentication required,' which implicitly distinguishes it from tools like discovery_login or discovery_account that require authentication, offering guidance on 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 adds valuable behavioral context beyond annotations: it explains the verification flow (sends a 6-digit code, requires follow-up with discovery_login_verify), specifies error conditions (404 if account doesn't exist), and clarifies use cases (lost key or new agent session). Annotations cover idempotency and non-destructiveness, but the description enriches this with practical workflow details.

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

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

The description is well-structured and front-loaded with the core purpose, followed by workflow details, usage guidelines, and parameter explanation. Every sentence adds value without redundancy, making it efficient and easy to parse.

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

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

Given the tool's complexity (authentication flow with verification), the description is complete: it covers purpose, workflow, error handling, alternatives, and parameter semantics. With annotations providing safety hints and an output schema presumably handling return values, no critical gaps remain.

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

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

With 0% schema description coverage, the description fully compensates by explaining the 'email' parameter's purpose ('Email address of the existing account'). It adds semantic meaning that the schema lacks, though it doesn't detail format constraints like email validation rules.

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 specific action ('Get a new API key for an existing Disco account') and distinguishes it from sibling tools by explicitly mentioning when to use discovery_signup instead. It provides a verb+resource combination that is precise and differentiated.

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

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

The description explicitly states when to use this tool ('Use this when you need an API key for an account that already exists') and when not to ('Returns 404 if no account exists with this email — use discovery_signup instead'). It also references the alternative tool discovery_login_verify for the next step, providing comprehensive guidance.

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

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

Annotations indicate non-destructive and idempotent behavior, which the description doesn't contradict. The description adds valuable context beyond annotations: it explains the verification process (6-digit code from email), specifies the expected input (same email as previous call), and mentions the output (new API key on success). However, it doesn't detail error cases or rate limits.

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

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

The description is front-loaded with the main purpose, followed by usage guidelines and parameter details in a structured 'Args' section. Every sentence adds value without redundancy, making it efficient and easy to parse.

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

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

Given the tool's complexity (authentication flow with verification), annotations cover safety aspects, and an output schema exists (so return values are documented elsewhere). The description provides good context on when and how to use it, parameter meanings, and the expected outcome. It could be more complete by mentioning error handling or dependencies, but it's largely adequate.

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 0%, so the description carries the full burden. It explains both parameters: 'email' as the address used in the previous call and 'code' as the 6-digit verification code from email. This adds clear meaning beyond the schema's basic types, though it could specify format constraints (e.g., email validation, code length).

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 specific action ('Complete login and receive a new API key'), distinguishes it from sibling tools like 'discovery_login' by specifying it's called after that tool returns a verification status, and identifies the resource involved (API key). It's not a tautology and provides clear differentiation.

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

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

The description explicitly states when to use this tool ('Call this after discovery_login returns {"status": "verification_required"}') and provides clear prerequisites (user receives a 6-digit code by email). It distinguishes it from the sibling 'discovery_login' by specifying the workflow sequence, though it doesn't mention other alternatives explicitly, but the context is sufficiently detailed.

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

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

Annotations indicate destructiveHint=true and idempotentHint=false, but the description adds valuable context beyond this: it specifies the cost ($0.10 per credit, $10 per pack), clarifies that credits are used for private analyses (with public ones free), and mentions the optional API key with environment variable fallback. This enriches understanding without contradicting annotations.

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

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

The description is well-structured and front-loaded with the core purpose, followed by pricing details, usage context, prerequisites, and parameter explanations. Every sentence adds value—no fluff or repetition—making it efficient and easy for an agent to parse quickly.

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 (a purchase operation with financial implications), the description is complete: it covers purpose, pricing, usage context, prerequisites, and parameters. With an output schema present, return values need not be explained, and annotations handle destructive/idempotent hints, so no gaps remain for effective agent 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 description coverage is 0%, so the description must compensate. It effectively explains both parameters: 'packs' is defined as 'Number of 100-credit packs to purchase' with a default, and 'api_key' is clarified as optional with an env var alternative. This adds essential meaning beyond the bare schema, though it could note data types or constraints more explicitly.

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 specific action ('Purchase Disco credit packs') and resource ('using a stored payment method'), distinguishing it from siblings like discovery_add_payment_method (which sets up payment) and discovery_analyze (which uses credits). It specifies the purpose is for buying credits, not other account actions.

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

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

It explicitly states when to use this tool ('Purchase Disco credit packs') and provides clear prerequisites ('Requires a payment method on file — use discovery_add_payment_method first'). It also distinguishes usage context by noting credits are for private analyses (public ones are free), guiding the agent away from unnecessary purchases.

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 destructiveHint=false and idempotentHint=true, but the description adds valuable behavioral context beyond this: it explains the verification flow with specific return values, mentions the free tier details, notes the 409 conflict response for existing emails, and clarifies authentication requirements. 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 efficiently structured with clear sections: purpose, process flow, tier details, authentication note, error case, and parameter explanations. Every sentence adds value without redundancy, and key information is 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 tool's complexity (signup with verification flow), the description is comprehensive: it covers purpose, usage flow, behavioral details, parameters, and error cases. With an output schema present, it appropriately omits detailed return value explanations, focusing on process context.

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

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

With 0% schema description coverage, the description compensates well by explaining both parameters: 'email' is for the new account and 'name' is optional with a default behavior (defaults to email local part). This adds meaningful semantics beyond the bare 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 specific action ('Create a Disco account and get an API key') and distinguishes it from sibling tools like 'discovery_signup_verify' by explaining the verification flow. It explicitly names the resource (Disco account) and outcome (API key).

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

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

The description provides explicit guidance on when to use this tool (to start signup) and when to use an alternative ('discovery_signup_verify' for completing verification). It also states 'No authentication required' and mentions prerequisites like email verification, making usage context clear.

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

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

Annotations indicate non-destructive and idempotent behavior, which the description doesn't contradict. The description adds valuable context beyond annotations: it explains the verification flow (6-digit code from email), success outcome (returns API key), and prerequisite state from discovery_signup. However, it doesn't mention rate limits or auth needs explicitly.

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 and front-loaded: first sentence states purpose, second provides usage context, third explains parameters and outcome. Every sentence adds value with zero waste, and the bullet-point style for args enhances readability without verbosity.

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

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

Given the tool's moderate complexity (verification step), annotations cover safety/idempotency, and an output schema exists (so return values needn't be explained), the description is complete. It covers purpose, usage, parameters, and outcome adequately without redundancy.

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 0%, so the description must compensate. It adds meaningful semantics for both parameters: 'email' is described as 'Email address used in the discovery_signup call' (tying it to prerequisite), and 'code' as '6-digit verification code from the email' (specifying format and source). This goes beyond the bare schema, though it doesn't detail validation rules.

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 specific action ('Complete Disco signup using an email verification code'), identifies the resource (signup process), and distinguishes it from sibling tools by referencing discovery_signup as a prerequisite. It goes beyond restating the name/title by explaining the verification mechanism.

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 this tool ('Call this after discovery_signup returns {"status": "verification_required"}'), provides a clear prerequisite, and distinguishes it from alternatives by specifying it's for verification after signup. No misleading or missing 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 valuable behavioral context beyond the readOnlyHint annotation: it specifies this is a polling tool for monitoring asynchronous runs, describes typical processing times (3-15 minutes), and explains the relationship with other tools in the workflow. No contradiction with the read-only annotation exists.

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

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

Perfectly structured and concise: purpose statement first, detailed return value documentation, clear usage guidelines, and parameter explanations. Every sentence adds essential information with zero 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 complexity (asynchronous status checking), the description provides complete context: purpose, detailed return values (making output schema redundant), workflow integration, parameter explanations, and behavioral expectations. The readOnlyHint annotation covers safety, and the description fills all other 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?

With 0% schema description coverage, the description compensates by explaining both parameters: run_id ('The run ID returned by discovery_analyze') and api_key ('Optional if DISCOVERY_API_KEY env var is set'). However, it doesn't provide format details or constraints beyond what's implied, leaving some semantic gaps.

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 with specific verb ('Check') and resource ('status of a Disco run'), distinguishing it from siblings like discovery_analyze (which initiates runs) and discovery_get_results (which fetches completed results). It provides a complete functional definition.

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

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

Explicit guidance is provided: 'Poll this after calling discovery_analyze' (when to use), 'Use discovery_get_results to fetch full results once status is "completed"' (alternative tool for next step), and context about typical runtime (3-15 minutes). This clearly defines the tool's role in the workflow.

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 destructiveHint=true (indicating a state-changing operation) and idempotentHint=true (safe to retry). The description adds valuable context beyond this: it specifies that paid plans require a payment method, credits roll over on paid plans, and the api_key can be omitted if set via environment variable. This clarifies authentication needs and billing implications.

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 purpose, followed by plan details and parameter explanations. Every sentence earns its place by providing critical information without redundancy, making it efficient and easy to parse.

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

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

Given the tool's complexity (subscription management with billing implications), the description is complete. It covers purpose, plans, requirements, and parameters. With annotations covering safety aspects and an output schema present (though not detailed here), no significant gaps remain for agent usage.

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

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

Schema description coverage is 0%, so the description fully compensates by explaining both parameters. It defines the 'plan' parameter with specific tier IDs and their details (names, prices, credits), and clarifies that 'api_key' is optional if DISCOVERY_API_KEY is set. This adds essential meaning not 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 the tool's purpose: 'Subscribe to or change your Disco plan.' It specifies the verb ('Subscribe to or change') and resource ('Disco plan'), and distinguishes it from sibling tools like discovery_list_plans (which lists plans) or discovery_add_payment_method (which handles payment setup).

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

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

The description provides clear context for when to use this tool by listing available plans and noting that paid plans require a payment method. It implies usage for subscription management but doesn't explicitly state when not to use it or name alternatives like discovery_purchase_credits for credit top-ups without plan changes.

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

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

The description adds valuable behavioral context beyond what annotations provide. While annotations only indicate it's non-destructive and non-idempotent, the description explains the tool's role in a workflow (precursor to discovery_analyze), provides practical constraints (size limits, context window limitations, local vs hosted server considerations), and clarifies authentication behavior (optional API key with fallback to env var). No contradiction with annotations exists.

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

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

The description is well-structured and efficiently organized. It starts with the core purpose and workflow integration, then provides clear parameter guidance. Every sentence serves a specific purpose with no wasted words. The bullet-point style parameter explanations are particularly effective for readability.

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 (5 parameters, workflow integration, multiple input methods) and the presence of an output schema (which handles return value documentation), the description is complete. It covers purpose, workflow context, parameter semantics, behavioral constraints, and authentication - everything needed for an agent to use this tool correctly without needing to infer missing information.

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

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

With 0% schema description coverage, the description fully compensates by providing comprehensive semantic information for all parameters. It explains the purpose of each parameter, when to use which one, practical constraints, and default behavior. The description adds significant value beyond the bare schema, especially with the mutually exclusive guidance about providing exactly one of file_url, file_path, or file_content.

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

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

The description clearly states the specific action ('Upload a dataset file') and the resource ('dataset file'), and distinguishes it from sibling tools by explicitly mentioning its relationship with 'discovery_analyze'. It provides a clear verb+resource combination with contextual differentiation.

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

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

The description provides explicit guidance on when to use this tool ('Call this before discovery_analyze') and how to use the output ('Pass the returned result directly to discovery_analyze as the file_ref argument'). It also offers clear alternatives within the tool itself (file_url vs file_path vs file_content) with context about when each is appropriate.

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