Disco

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds useful context about what is returned (plan, credits, payment method status) but does not cover potential errors or edge cases. Given the annotation coverage, a score of 3 is appropriate.

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

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

The description is concise and well-structured: a one-line purpose, a brief explanation of return values, a usage scenario, and an Args note. Every sentence contributes without redundancy, making it easy to scan.

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

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

Given the simple single-parameter tool, the readOnly annotation, and the presence of an output schema, the description covers the essential context: purpose, usage scenario, and parameter behavior. It does not mention prerequisites like having an account, but the context signals suggest this is not critical for selection.

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 only parameter, api_key, is explained in the Args section: 'Disco API key (disco_...)'. This adds format details and the env var fallback, which are not present in the schema. The schema only gives a type and default, so the description meaningfully compensates for the 0% schema coverage.

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

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

The description opens with 'Check your Disco account status', which is a specific verb and resource. It lists the returned fields (plan, credits, payment method status), making the purpose clear. It does not explicitly distinguish from the sibling 'discovery_status', but the focus on account information is 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 provides an explicit usage scenario: 'Use this to verify you have sufficient credits before running a private analysis.' This tells the agent when to invoke the tool. It does not mention alternatives or when not to use it, but the guidance is more than implied.

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 idempotentHint and destructiveHint, but description adds meaningful behavioral context: card details never touch Disco's servers, and the tool is a prerequisite for other operations. It doesn't fully explain whether repeated calls with different IDs attach multiple methods, but no annotation contradiction exists.

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

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

Structured in digestible sections: purpose, requirement, tokenization instructions, and Args. Each sentence adds value; no redundancy or filler. Suitable length for a tool involving external dependencies.

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?

This tool involves external Stripe tokenization and a prerequisite boundary. The description covers the full flow, parameter semantics, and security context. Output schema exists, so return details don't need description. Minor gap: does not state whether multiple payment methods can be attached, but this may be beyond purpose.

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 zero property descriptions; the description fully explains both parameters: payment_method_id format (pm_...) and api_key optionality with DISCOVERY_API_KEY env var. This exceeds schema coverage.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Attach a Stripe payment method to your Disco account.' It further distinguishes itself from sibling tools by noting it is required before purchasing credits or subscribing, making it contextual among discovery_purchase_credits and discovery_subscribe.

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 tells the agent when this tool is needed (before purchasing credits or subscribing), and when not via the prerequisite that the payment method must be tokenized through Stripe's API first. It even provides the exact Stripe endpoint as an alternative step, making the decision boundary 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?

The description extensively discloses behavioral traits beyond annotations: it is a long-running operation that returns a run_id immediately, public runs are free but publish results, private runs cost credits, and private report URLs require sign-in. It also reveals side effects like publishing and credit consumption, which aligns with the destructiveHint:true annotation (non-idempotent, resource-consuming). No contradiction found.

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

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

The description is long but every section earns its place. It opens with a clear summary, then covers workflow, cost/privacy implications, authentication, and prerequisites. Bolded phrases and paragraph breaks make it scannable. No filler or repetition exists; all content is operational guidance an agent needs.

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, side effects, long-running nature), the description is remarkably complete. It explains the immediate return (run_id), how to retrieve results (discovery_status and discovery_get_results), prerequisites (discovery_upload), cost/publication tradeoffs, and authentication fallback. The output schema likely details result structure, so not explaining it is acceptable. The description leaves no critical operational gap.

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

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

Although the schema has zero description coverage, the tool description includes a dedicated 'Args' section that explains every parameter: target_column, file_ref, analysis_depth, visibility, title, description, excluded_columns, column_descriptions, author, source_url, use_llms, and api_key. It adds meaningful guidance, such as defaults, the distinction between public/private, and the recommendation to always provide column_descriptions for non-obvious names. This fully compensates for the schema's lack of 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 opens with a specific verb and resource: 'Run Disco on tabular data to find novel, statistically validated patterns.' It clearly distinguishes itself from generic data analysis ('NOT another data analyst') and from sibling tools like discovery_upload, discovery_status, and discovery_get_results. The purpose is unmistakable and precisely scoped.

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

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

The description explicitly states when to use the tool ('when you need to go beyond answering questions... finding things nobody thought to ask') and when NOT to use it ('Do NOT use for summary statistics, visualization, or SQL queries'). It also provides a clear workflow: call discovery_upload first, then pass file_ref, poll with discovery_status, and fetch results with discovery_get_results. Alternatives are named directly.

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

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

Provides extensive behavioral details beyond the readOnlyHint annotation: public analyses always cost 0, private costs split by LLM usage, and response includes depth caps and file formats. Also explains optional API key behavior and available credits. 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?

Well-structured with a clear opening, bullet-like details, and an Args list. Every sentence adds value, and the description is appropriately sized for the tool's complexity.

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

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

Comprehensive for a pre-flight estimation tool: describes return values, explains cost logic, provides usage context, and covers all parameters. Output schema exists but the description already echoes key return fields, making it self-contained.

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

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

Schema descriptions are absent, but the Args section thoroughly explains each parameter (file_size_mb, num_columns, analysis_depth, api_key) including defaults and effects on the estimate. Fully compensates for schema 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?

Clearly states 'Estimate the credits required to run a Disco analysis' with a specific verb and resource. Distinguishes from sibling tools like discovery_analyze, which actually runs the 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?

Explicitly instructs to call before discovery_analyze when cost or feasibility is unclear, and clarifies authentication requirements. Names the related tool and provides clear when-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?

Annotations provide readOnlyHint: true, and the description adds the critical behavioral constraint of only being callable after a run completes. It does not contradict annotations. It also describes the structure of the response, including the dashboard_urls object and what each page contains. While auth via api_key is mentioned in params, the description doesn't detail rate limits or error behavior, so a small gap remains.

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: a one-line purpose, a concise list of returned content, a detailed but organized bullet list for dashboard URLs, a clear prerequisite, and a straightforward Args section. Every sentence earns its place and the most important information (purpose and precondition) 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?

For a tool that returns a complex results object, the description adequately covers response contents, dashboard navigation, the dependency on a completed run, and parameter semantics. The presence of an output schema means it needn't enumerate every field, but it provides enough context for an agent to select and invoke the tool correctly. The only minor gap is lack of error/edge-case handling, but that's not essential.

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 0% (no descriptions in schema for the two parameters), but the description fully documents both: run_id is defined as 'The run ID returned by discovery_analyze,' and api_key is described with format 'disco_...' and the fallback to DISCOVERY_API_KEY env var. This adds essential meaning 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 opens with a specific verb and resource: 'Fetch the full results of a completed Disco run.' It enumerates the returned components (patterns, feature importance, summary, column statistics, suggestions), which distinguishes it from siblings like discovery_status (status checking) and discovery_analyze (starting analysis). The dashboard_urls breakdown further clarifies the tool's scope.

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 'Only call this after discovery_status returns "completed".' This gives a clear precondition and directs the user to the alternative status-checking tool. The dashboard_urls section also provides guidance on when to use which result view.

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

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

Beyond the readOnlyHint annotation, the description discloses 'No authentication required' and 'Returns all available subscription tiers with credit allowances and pricing,' providing useful behavioral context about output and access. There are 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 three concise sentences, each adding distinct value: purpose, authentication requirement, return details, and usage guidance. There is no fluff or redundancy.

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

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

For a simple list tool with no parameters and an output schema, the description adequately covers what the tool does, what data it returns, and when to use it. It is fully self-contained and appropriate 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?

The tool has zero parameters, so the baseline is 4. The description correctly avoids mentioning parameters, and the schema already covers the empty parameter set. No further parameter explanation is needed.

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

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

The description uses a specific verb ('List') with a clear resource ('Disco plans') and scope ('with pricing'), and it differentiates from sibling tools like discovery_purchase_credits or discovery_subscribe by focusing on plan listing. The purpose is unambiguous.

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

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

The description explicitly states 'Use this to help users choose a plan,' giving a clear use case. It also notes 'No authentication required,' which sets context for when the tool can be invoked. It does not explicitly mention alternatives, so it falls short of a perfect 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?

The description discloses the email verification code step, the need to call discovery_login_verify, and the 404 error case. Annotations only provide idempotentHint and destructiveHint, so this adds substantial behavioral context beyond the structured metadata.

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

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

The description is compact, front-loaded with the main purpose, and uses short paragraphs with clear logical progression. Every sentence earns its place without redundancy.

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

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

For a multi-step login flow, the description covers the prerequisite (verification code), the next step (login_verify), error handling (404), and the alternative (signup). It is complete without needing an output schema.

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

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

The schema only provides the parameter name 'email' with title 'Email'. The description adds 'Email address of the existing account,' clarifying that it must be an existing account (not a new one), which is meaningful despite being concise.

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

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

The description opens with a specific verb and resource: 'Get a new API key for an existing Disco account.' It clearly distinguishes this from siblings like discovery_signup (existing vs new account) and discovery_login_verify (the follow-up step).

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: 'when you need an API key for an account that already exists' with concrete examples, and gives an alternative: 'use discovery_signup instead' if a 404 occurs. This is textbook usage guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds meaningful context: the user receives a 6-digit code by email, the email must match the earlier call, and a new API key is returned on success. No contradiction with annotations, though it stops short of detailing edge cases like invalid codes or key rotation.

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

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

The description is compact and front-loaded. The first sentence states the purpose, the second provides the required trigger condition, and the Args section is clear and minimal. Every sentence contributes useful information without redundancy.

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

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

For a two-parameter verification tool with annotations and an output schema, the description covers the complete workflow: preconditions, exact inputs, and the success return value. No critical gaps are apparent, and the output schema handles return structure details.

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

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

Although structured schema coverage is 0%, the description manually documents both parameters with clear semantics: 'email' is the address used in the discovery_login call, and 'code' is the 6-digit verification code from the email. This fully compensates for the schema's lack of descriptions and adds relationship context that the schema cannot convey.

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 states the tool's core action: 'Complete login and receive a new API key.' It clearly distinguishes from sibling tools by specifying it is the follow-up to discovery_login when verification is required. The verb and resource 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?

Provides explicit when-to-use guidance: 'Call this after discovery_login returns {"status": "verification_required"}.' This clearly sequences the tool relative to discovery_login. It does not explicitly discuss when not to use it or alternatives, but the precondition is strong and actionable.

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

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

Annotations already flag this as destructive and non-idempotent. The description adds meaningful context by disclosing the cost per credit, pack size, and the necessity of a stored payment method, which collectively imply a monetary charge. It does not describe failure modes or post-purchase effects, but the annotation coverage already handles the core safety profile, so the additional context is valuable.

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 tightly organized: it opens with the purpose, follows with cost and usage context, states a prerequisite, and ends with a compact Args section. Every sentence serves a clear function and there is no extraneous information, making it easy to quickly 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?

With two parameters, an output schema, and annotations present, the description covers purpose, pricing, prerequisite, parameter semantics, and usage context. It leaves little ambiguity. A small gap is the lack of explicit statement about what happens after a successful purchase (e.g., credits added to account), but given the output schema, the agent can infer the response, so this is a minor gap.

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 0%, so the description must compensate, and it does so fully. 'packs' is explained as the number of 100-credit packs with a default of 1, and 'api_key' is described as the Disco API key with an environment variable fallback. This adds detailed meaning that the 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 states the exact action with a specific verb and resource: 'Purchase Disco credit packs using a stored payment method.' It clearly distinguishes itself from siblings like discovery_add_payment_method by focusing on the purchase itself, and even names the use case (private analyses). This is unambiguous and 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?

The description explicitly tells the agent to use discovery_add_payment_method first as a prerequisite, which is a clear 'when-to-use' signal. It also provides context that credits are for private analyses, implying this tool is needed when private analyses are required. However, it does not explicitly list when not to use it or alternative tools (e.g., discovery_subscribe), so it falls just short of 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?

The description goes well beyond the annotations (idempotentHint, destructiveHint) by disclosing key behaviors: returns verification_required with a 6-digit code, free tier activation, 409 for existing email, and no authentication required. This provides rich context about what happens during the signup flow, including the two-step process and error handling.

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

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

The description is appropriately sized and front-loaded with the main purpose. It uses a clear structure: one-sentence summary, flow explanation, notes, and parameter list. While slightly longer than minimal, every sentence adds necessary detail for correct 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?

For a signup tool with a two-step flow, the description thoroughly covers the complete lifecycle: initial request, verification requirement, next step (discovery_signup_verify), free tier behavior, auth requirement, and error condition (409). It is comprehensive enough for an agent to know what to expect and how to proceed.

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: 'email: Email address for the new account' and 'name: Display name (optional — defaults to email local part)'. It adds important semantics like optionality and default behavior not present 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 explicitly states 'Create a Disco account and get an API key', using a specific verb and resource. It clearly distinguishes itself from sibling tools like discovery_login and discovery_signup_verify by describing the signup flow and pointing to the verification step.

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 when-to-use guidance by describing the signup flow and directing users to call discovery_signup_verify after verification. It also implies when not to use (e.g., when email is already registered, a 409 is returned, suggesting login instead). However, it does not explicitly name alternative tools or state when to use them, only implicitly differentiating via the flow.

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 idempotentHint=true and destructiveHint=false, so the description does not need to repeat those. It adds meaningful behavioral context: the trigger condition (must follow discovery_signup), the fact that the user receives a 6-digit code by email, and that an API key is returned on success. This goes beyond annotations, though it does not cover failure modes or rate limits, which are absent.

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

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

The description is concise and well-structured: a one-sentence summary, then usage context, then an Args block. Every sentence provides necessary information without fluff or redundancy. It is front-loaded with the main purpose and gives parameters in a clear list.

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 two-parameter verification tool with an output schema and annotations, the description is complete. It explains the prerequisite step, the exact inputs, and the success result. Error handling is not described but is likely covered by the output schema. There are no significant gaps given 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 0% with no descriptions, so the description carries the full burden of parameter explanation. It does so effectively: 'email: Email address used in the discovery_signup call' and 'code: 6-digit verification code from the email.' This clarifies that the email must match the prior signup call and the code is the 6-digit email code, which is exactly what the 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 tool's purpose: 'Complete Disco signup using an email verification code.' This uses a specific verb ('complete') and resource ('Disco signup'), and distinguishes itself from discovery_signup (which initiates) and discovery_login_verify (which is for login) by explicitly focusing on the signup verification step.

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

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

The description gives explicit when-to-use guidance: 'Call this after discovery_signup returns {"status": "verification_required"}.' It also instructs to use the same email address as in the signup call, clarifying the required prerequisite and input consistency. This is strong, direct usage guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful behavioral context: the status enumeration, queue position semantics, active pipeline step, and estimated wait time. It also clarifies the api_key fallback to environment variable. 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?

Concise yet information-dense. The bullet list of returned fields is well-organized, and the Args section is clearly separated. Every sentence contributes to usage or parameter understanding without fluff.

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

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

Covers the full workflow: what to call before, how to poll, what fields to expect, and what to call after. Includes parameter explanations and auth fallback. The output schema exists, but the description still enriches understanding of queue behavior and statuses. Complete for this 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 has 0% description coverage, but the description fully compensates by defining both parameters: 'run_id: The run ID returned by discovery_analyze' and 'api_key: Disco API key (disco_...). Optional if DISCOVERY_API_KEY env var is set.' This adds meaning beyond the raw 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 starts with a specific verb + resource: 'Check the status of a Disco run.' This clearly distinguishes from siblings like discovery_analyze (start) and discovery_get_results (fetch results). The purpose is immediately evident.

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: 'Poll this after calling discovery_analyze.' Also names the alternative for when the run completes: 'Use discovery_get_results to fetch full results once status is "completed".' This is excellent contextual 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 include idempotentHint and destructiveHint. The description adds useful context about payment method requirements and credit rollover, but does not explain the destructive implications of changing plans (e.g., potential loss of current plan features). It does not contradict the annotations, but it doesn't fully elaborate on the destructive behavior.

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

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

The description is well-structured with a clear purpose statement, a bulleted list of plans, and an args section. Each sentence provides relevant information, with no filler or redundancy. It is slightly long but remains concise given the level of detail.

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

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

The description covers key aspects: plan options, pricing, payment requirement, credit rollover, and API key handling. Since an output schema exists, return details are not required. It lacks error handling or side-effect details, but overall it is reasonably 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?

The input schema has 0% description coverage, but the tool description compensates by defining valid plan values ('free_tier', 'tier_1', 'tier_2') and explaining the api_key format and optionality. This adds meaningful semantics beyond the schema's simple type declarations.

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 for subscribing to or changing a Disco plan, using a specific verb and resource. It distinguishes from siblings like discovery_purchase_credits and discovery_list_plans by focusing on the plan subscription/change action.

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

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

The description provides context (plan details, payment requirement, credits rollover) but does not explicitly state when to use this tool versus alternatives such as discovery_purchase_credits. It implies usage for plan management but lacks explicit exclusions or alternative guidance.

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

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

Annotations provide only idempotentHint=false and destructiveHint=false, which are minimal. The description adds meaningful operational context: the server downloads URLs directly, file_path only works locally with no size limit, file_content is base64 with context window limits, and API key can come from an env var. This exceeds annotation coverage, though it doesn't detail failure behaviors or retry semantics.

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 action and workflow, then provides a clean bulleted list for parameters. Each sentence adds value without redundancy, and the format is easy to scan.

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

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

With five parameters and an output schema present, the description covers the full workflow: upload prerequisites (API key), three mutually exclusive input modes, filename behavior, and the intended use of the returned file reference. It is complete for an AI agent to successfully invoke the tool.

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

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

Schema coverage is 0% (no descriptions in input schema), so the description must fully explain each parameter. It does: file_url, file_path, file_content, file_name (with default and usage constraint), and api_key (optional if env var set). Every parameter is addressed with usage context and 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 uses a specific verb and resource: 'Upload a dataset file and return a file reference for use with discovery_analyze.' This clearly distinguishes it from sibling tools like discovery_analyze and discovery_get_results, stating both the action and its downstream 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?

Provides explicit call order: 'Call this before discovery_analyze. Pass the returned result directly to discovery_analyze as the file_ref argument.' It also gives guidance on choosing between file_url, file_path, and file_content based on context (remote vs local, size limits), making alternatives clear.

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