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

Annotations already provide readOnlyHint=false and destructiveHint=true; the description adds OAuth authentication and the uniform POST+JSON body behavior. However, it does not add much context about the destructive nature, failure modes, or response behavior. It does not contradict 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?

Three sentences, front-loaded with the core purpose, and no filler. Every sentence adds either usage guidance or a critical constraint.

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 generic fallback tool with no output schema, the description covers the essential mechanics: path/action/params construction, OAuth auth, workspace scoping, and billing exclusions. It could include a concrete example or error-handling note, but the current coverage is strong for its 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 description coverage is 100%, so the baseline is 3. The description adds useful framing about the JSON body shape and that params are merged, but it mostly re-states what the schema already documents.

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

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

The description clearly states this tool is an escape hatch for calling any DPF API action when no dedicated tool exists. It names the verb+resource (POST to DPF API path) and explicitly differentiates itself from all the sibling dedicated tools.

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

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

It explicitly says to use this tool when there is no dedicated tool, and gives a clear exclusion: billing mutations are not available via MCP and should go through the DPF web UI. This is strong when/when-not guidance with an alternative.

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

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

Annotations already declare the tool is not read-only, not idempotent, and not destructive. The description adds the ownership detail and implies the creation side effect. For a simple create operation, this covers the key behavioral aspects, though it could briefly mention rate limits or default permissions.

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

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

Two short sentences, the first states the action and owner, the second gives a conditional usage hint. No fluff, perfectly front-loaded, and every word contributes to clarity.

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 (2 params, no nested objects, no output schema), the description, together with the rich annotations and full schema coverage, provides enough context for an agent to use it correctly. It even includes a conditional usage hint that preempts common errors.

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

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

Schema description coverage is 100% for both 'name' and 'description', so the schema already explains the parameters. The tool description does not add extra context (e.g., validation rules, format); this meets the baseline but does not exceed it.

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 starts with 'Create a new workspace' — a specific verb and resource — and adds ownership context ('owned by the authenticated user'). It is immediately clear what the tool does and it does not risk being confused with any sibling tool, as no other workspace-creation tool exists.

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 sentence 'Use this if list_my_workspaces returns none' gives an explicit condition and names the alternative tool. This directly tells the agent when to invoke this tool versus relying on a list operation, which is exactly what a high-quality usage guideline should do.

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?

While annotations already indicate destructive and idempotent behavior, the description adds 'permanently' and explicitly mentions that associated configuration is also deleted, which goes slightly beyond the annotations. However, it does not describe side effects like Cascading deletes or error conditions.

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

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

The description is a single, succinct sentence that conveys the essential information without any redundant wording or unnecessary details.

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

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

For a simple delete operation, the description is sufficient, especially given the schema and annotations. It mentions the deletion of both the spec and its configuration, which covers the primary context. A minor omission is lack of mention of whether the operation is recoverable, but 'permanently' already implies that.

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

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

The schema already provides descriptions for each parameter (specName and workspaceId) with 100% coverage. The tool description does not add further detail beyond the schema, so it meets the baseline but does not enhance understanding.

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

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

The description clearly states the action (delete), the target resource (data spec and associated configuration), and adds 'permanently' to emphasize irreversibility. It is specific and easily distinguishes from other tools.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor any cautionary notes about the destructive nature beyond the verb itself. It does not clarify scenarios where deletion should be avoided or prerequisites.

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

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

Annotations say readOnly=false, idempotentHint=true, destructive=false. The description adds that it waits synchronously until job completion or failure, and implies potential timeout behavior. This is valuable context beyond annotations and does not contradict them.

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

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

Two concise sentences front-load the main action, with no redundant wording. The conditional polling advice is included without padding.

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

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

For a tool with 3 parameters and no output schema, the description is thorough: it covers when to call, what happens (waits), timeout handling, and the alternative to polling. Annotated idempotence supports retry safety.

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 already describes all parameters with 100% coverage. The description references jobId from run_data_job and implies specName is tied to the job, adding workflow context that enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: to start processing after uploading files from run_data_job and wait for completion or failure. It specifically distinguishes from siblings by referencing the previous step and alternative polling with get_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?

Explicitly states when to use: after uploading files returned by run_data_job. Also gives guidance on what to do if it times out (poll with get_status instead of re-calling), providing a clear alternative.

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 safety profile is known. The description adds that the tool waits for a terminal state and should not be re-called on timeout—behavioral traits not covered by annotations. This is useful but not exhaustive (e.g., what happens on failure is implied but not detailed).

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

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

Two sentences, front-loaded with the core action and followed by a specific fallback instruction. No filler, perfectly concise.

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

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

Given four parameters (two required), an outputless spec, and a clear two-step onboarding flow, the description covers the essential context: when to call, what it does, and how to handle timeouts. It could mention return values, but the summary of waiting for 'ready' or 'failed' is sufficient for the agent to decide next steps.

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 has 100% parameter description coverage. The description adds minimal extra meaning—it implies specId is the one returned by onboard_data_source and that loadSampleData triggers a data-load job. That context is helpful but does not significantly exceed the schema's own descriptions, so a baseline 3 is appropriate.

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

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

The description clearly states the tool's role: it kicks off AI analysis after uploading and waits for a terminal state ('ready' or 'failed'). It explicitly references the prior step (onboard_data_source) and distinguishes itself from polling via get_status, making it unmistakable among siblings.

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

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

Provides explicit sequence guidance: 'Call after uploading the file(s) returned by onboard_data_source' and instructs to 'Poll with get_status instead of re-calling this if it times out.' This clarifies when to invoke the tool and when to use an alternative, which is exactly what agents need.

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

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

The description goes beyond annotations by disclosing that the call waits synchronously for a terminal state ('ready' or 'failed') and may time out. It also implicitly warns against re-calling, aligning with idempotentHint=false. 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?

Two sentences, no fluff. The first sentence provides the purpose and the second gives timeout handling. Information is front-loaded and every word earns its place.

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

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

Given the tool's role in a multi-step workflow and the rich schema, the description is complete: it explains the prerequisite (update_data_spec), the behavior (waits for ready/failed), and the fallback (get_status). No output schema is present, but the outcome is clearly stated.

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

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

Schema coverage is 100%, with each parameter already described. The tool description adds little beyond the schema; the only slight addition is referencing that specId comes from update_data_spec, but that info is already in the schema description. Baseline 3 applies.

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

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

The description clearly identifies the tool as step 2 of a data spec update workflow ('after uploading the file(s) returned by update_data_spec'), and states its specific action: kicks off AI analysis and waits for 'ready' or 'failed'. It also distinguishes itself from siblings by referencing the poll alternative (get_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?

Explicitly says when to call ('after uploading the file(s) returned by update_data_spec') and provides a clear alternative for timeout situations ('Poll with get_status instead of re-calling this if it times out'). This is direct and actionable 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, idempotentHint=true, and destructiveHint=false, covering safety. The description adds value by specifying the terminal states for each resource type and the constraint 'exactly one of specId or jobId', which enriches understanding of behavior beyond the annotations.

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

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

The description is extremely concise—two sentences—and front-loads the purpose and key constraints. Every word contributes, with no redundancy or filler.

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

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

The tool is a simple status poll with three parameters and no output schema. The description covers both use cases, the required parameter selection, and expected terminal states. It does not describe the return format, but for a status tool this may be assumed; overall, it is sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100% with each parameter (jobId, specId, workspaceId) described directly. The description essentially echoes the mutual exclusivity already present in the schema and adds terminal states, but these are behavioral details rather than parameter semantics. Thus, it does not substantially enhance parameter understanding beyond the schema.

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

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

The description clearly states it polls status for two distinct resources (data spec analysis or data-load job) with specific terminal states ('ready'/'failed' and 'complete'/'failed'), and explicitly distinguishes the parameter use. It is specific and differentiates from sibling tools that perform actions like run/finish data jobs.

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: when to poll status (during analysis or job execution) and the required mutual exclusivity of specId/jobId. It does not explicitly mention alternative tools, but the action 'poll' makes its role obvious among siblings like run_data_job or finish_data_job.

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 cover read-only, idempotent, and non-destructive behavior. The description adds context about pagination and ordering, which goes beyond annotations, but does not introduce additional behavioral caveats. Overall, it sufficiently 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 concise, using two sentences to convey the primary purpose, pagination details, and a key distinction from a sibling tool. It is well-structured, starting with the core functionality and then adding supporting details and alternative references.

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

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

Given the lack of an output schema, the description adequately covers the tool's actions, parameters, and pagination. It does not address potential errors or permissions, but these are not required for a simple listing operation. The description is complete enough for typical usage.

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

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

The schema already describes all parameters, but the description adds meaningful context by explaining what 'specs' and 'jobs' represent (parsing/mapping rule sets vs. executions). It also clarifies the pagination mechanism, reinforcing the parameter descriptions without redundancy.

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

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

The description clearly states that the tool lists either data specs or data processing jobs, with brief definitions of each. It also explicitly contrasts with a sibling tool for table listing, leaving no ambiguity about the tool's 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?

It provides explicit guidance on when to use this tool versus alternatives, such as using submit_query for live table listings. Pagination instructions (default page size, max, and cursor usage) are also clearly stated, covering practical usage scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by specifying that the result includes the user's permission on each workspace, which is not captured in annotations. This additional behavioral detail is useful and does not contradict the annotations.

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

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

The description is a single, concise sentence that immediately states the action and scope. It is front-loaded and contains no filler or redundant information, making it highly efficient.

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

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

With zero parameters, a read-only operation, and no output schema, the description covers everything needed: it specifies what is listed and that permissions are included, which hints at the return structure. No additional information is necessary for an agent to correctly invoke and interpret 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?

There are zero parameters, so the description does not need to explain parameter semantics. The schema is empty, making coverage effectively 100%. The description adds no parameter info because none exists, and the tool is so simple that the baseline of 4 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('every workspace the authenticated user has access to') and distinguishes itself from sibling tools by adding 'including their permission on each,' which sets it apart from generic listing tools like list_data and creation tools like create_workspace.

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

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

The description clearly indicates the tool lists workspaces accessible to the user, which implicitly tells when to use it (when you need to see accessible workspaces). It does not explicitly call out alternatives or exclusions, but the purpose is so specific that no further guidance is needed among the given siblings.

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

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

The description adds concrete behavioral details beyond annotations: for sftp create generates a keypair and returns the public key; for aws_s3 create generates an ExternalId and trust policy. It also states the testing requirement. Annotations already signal mutating/destructive behavior, so this is consistent.

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

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

The description is concise, two sentences plus a requirement clause, yet covers the main actions and per-type details without redundancy. It is well-structured for quick parsing.

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

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

The description provides essential context: it lists actions, per-type specifics, and a prerequisite (must pass test before use in trigger). However, it doesn't mention potential side effects like cost or irreversibility of delete, but given the annotations already indicate destructive action, this is acceptable.

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

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

All 7 parameters have descriptions in the schema, and the description clarifies type-specific requirements (e.g., roleArn for aws_s3, hostname/username for sftp). Defaults for type and workspaceId are specified. This fully covers parameter semantics.

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

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

The description clearly states the tool manages external data-source connections via create, list, test, or delete actions. It explicitly covers both supported types (sftp and aws_s3) with distinct behaviors, making it easy to distinguish from sibling tools like onboard_data_source or manage triggers.

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

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

The description explains when each action is appropriate (e.g., create for new connections, test before use) and mentions a prerequisite: connection must pass test before it can be used in a trigger. It doesn't explicitly name alternative tools, but the context is clear enough for an agent to decide when to invoke it.

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

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

Annotations already indicate that the tool is not read-only and is destructive. The description does not add details about side effects (e.g., deletion effects, auth requirements, or rate limits). It is transparent about actions but lacks deeper behavioral 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 concise, using two sentences to convey the core functionality and pointing to run-history. It is well-structured and free of unnecessary filler.

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

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

Given the tool's complexity (19 parameters, nested objects, multiple actions), the description is adequate but could be more complete. It covers the main actions and types, but does not mention potential constraints like required dependencies between parameters or default behaviors beyond what the schema already states.

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

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

The input schema has 100% description coverage for all 19 parameters, so the baseline is 3. The description itself does not add additional meaning beyond the schema annotations, such as clarifying relationships between parameters or edge cases.

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 create, list, update, delete, or fire a workspace job trigger, and lists specific trigger types and actions. It also directs users to the run-history action for monitoring, which distinguishes its scope from siblings.

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

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

The description provides some guidance by listing supported actions and trigger types, and mentions using run-history for monitoring. However, it does not explicitly contrast with alternative tools like setup_scheduled_pull or run_data_job, leaving some ambiguity about when to choose this tool over those.

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

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

Annotations provide no safety hints, so the description carries the burden. It discloses key behaviors: for file it returns presigned URLs, for tables it uses AI-generated SQL and requires autoRefresh. It also explains the two-step flow. While it doesn't discuss side effects or error conditions, it adds valuable context beyond the schema.

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

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

The description is two sentences that efficiently convey the core purpose, both modes, the upload URL flow, the next step, and the autoRefresh requirement. It is front-loaded with the purpose and contains no unnecessary words.

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

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

The description covers the two modes and autoRefresh, but leaves ambiguity about whether finish_data_source_onboarding is required for tables mode as well, and does not clarify what the tool returns for tables (e.g., a spec ID). Given the tool's complexity (15 params, nested objects, no output schema), it could be more explicit about expected outputs and follow-up steps for both modes.

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

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

Schema coverage is 100%, so parameters are well-documented. The description enriches this by clarifying conditional dependencies (e.g., sourceType tables requires autoRefresh, sourceType file requires sampleFileName and yields upload URLs) and explaining autoRefresh values. This adds meaning beyond the schema's individual descriptions.

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

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

The description clearly states the tool creates a data spec as the first step of data source onboarding, with distinct behaviors for file (presigned upload URLs) and tables (AI-generated SQL). It explicitly references the follow-up step (finish_data_source_onboarding), distinguishing it from sibling tools like update_data_spec or finish_data_source_onboarding.

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 positions this as the first step and instructs calling finish_data_source_onboarding after upload for the file mode, but does not explicitly state when to use this vs. alternatives like update_data_spec. It does clarify the file vs. tables modes and the autoRefresh requirement, providing sufficient context for typical use cases.

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 false hints, so no safety information. The description discloses that it creates a job and returns upload URLs, and that the agent must upload and then call a second tool. It does not describe potential side effects like whether the job is visible in status, what happens on failure, or any resource consumption. It adds some context beyond annotations but lacks deeper behavioral detail.

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

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

The description is three concise sentences: the first states purpose, the second gives the next action, and the third gives a usage condition. It is front-loaded with 'First step' and contains no redundant filler. Every sentence adds value.

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

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

For a step-1 tool, the description explains the full workflow: create job, get upload URLs, upload, then call finish_data_job. It also notes the 'beyond the initial sample' condition. There is no output schema, but the description mentions returning upload URLs. It could mention error handling or what happens if the upload fails, but overall it covers the essential context for this stage.

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 already covers all parameters with descriptions (100% coverage). The description reinforces that specName refers to an 'already-configured data spec' and that fileNames are for the files to process, but adds no new syntax or format details. It also does not elaborate on workspaceId beyond the schema's default mention. With full schema coverage, a score of 3 is appropriate.

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

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

The title explicitly labels this as 'step 1: create job and get upload URL(s)' and the description repeats that with a clear verb+resource: 'creates a job and returns upload URL(s)'. It distinguishes from the sibling finish_data_job by stating it is the first step and instructs to call finish_data_job after uploading.

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 clear sequential guidance: 'Upload, then call finish_data_job' and a condition 'Only for files beyond the initial sample.' It implies alternatives (finish_data_job for the next step) but does not explicitly mention when to use other tools like setup_scheduled_pull or delete_data_spec. It is clear enough for this step-based 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?

The description discloses key side effects beyond annotations: it reuses a matching connection if one exists, otherwise creates one, tests it, and creates a trigger. This adds meaningful behavioral context to the openWorldHint and idempotentHint flags, though it doesn't detail duplicate-trigger behavior or auth requirements.

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

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

Two sentences, front-loaded with purpose, and no filler. The second sentence earns its place by resolving the main protocol ambiguity.

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

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

For a complex 11-param tool with no output schema, the description covers the workflow, protocol selection, and prerequisite (already-analyzed spec). It doesn't mention return values or what happens if a trigger already exists, but the schema handles remaining parameter 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?

Schema coverage is 100%, so the baseline is 3. The description adds conditional routing between SFTP and S3 ('Pass hostname for sftp, or roleArn (+ s3Bucket) for aws_s3') and clarifies that specName must be an already-analyzed spec, which is valuable beyond the schema.

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

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

The description opens with 'End-to-end setup for...' and names the exact resources involved: SFTP/S3, connection, trigger, and an already-analyzed spec. It clearly distinguishes this from sibling tools like manage_connection and manage_trigger by framing it as a complete setup workflow.

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 clearly indicates this is for scheduled pulls into an already-analyzed spec and gives protocol-specific parameter guidance ('Pass hostname for sftp, or roleArn (+ s3Bucket) for aws_s3'). It doesn't explicitly contrast with alternatives like manage_connection or run_data_job, so it stops 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description complements this by explaining the execution context: Iceberg tables in a workspace, and the constraint against schema-qualified names. It doesn't contradict annotations, and the brief directive to use SHOW TABLES adds a behavioral insight beyond the annotations.

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

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

Three short sentences with zero fluff. The core action, a practical tip (SHOW TABLES), and a key constraint are packed into 35 words, all front-loaded. Every word contributes.

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

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

For a simple read-only tool with two parameters and complete schema coverage, this description is sufficient. It covers what (SQL query), where (workspace Iceberg tables), and how (table-name only references). The only minor gap is an explicit statement of return format, but with no output schema and simple types, it's not necessary.

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 covers both parameters with descriptions, including an example for 'sql'. The tool description adds extra meaning by specifying that queries run against Iceberg tables in a workspace and that table names must not be schema-qualified, directly informing how to form the 'sql' parameter. This goes beyond the schema's baseline.

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

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

The description opens with a specific verb+resource: 'Run a SQL query against the Iceberg tables loaded into a workspace.' This clearly distinguishes it from sibling tools like 'run_data_job' or 'list_data' by pinpointing the Iceberg SQL querying context and the workspace 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?

It provides direct usage guidance: 'Run SHOW TABLES to list the tables that actually exist' and 'Reference tables by name only'. While it doesn't explicitly name alternatives, the instruction to use SHOW TABLES for discovery implies a workflow and sets expectations for table qualification, which is valuable for an agent.

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

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

While annotations already indicate the tool is not read-only and is idempotent, the description adds rich behavioral context: it saves changes, re-runs analysis by default, and supports a two-phase upload flow with replacement files. This goes beyond the schema and annotations, covering both synchronous and upload-based execution paths without contradicting any annotations.

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

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

The description is concise, with four purposeful sentences: stating the action, describing synchronous behavior, explaining the upload flow, and advising on parameter usage. It is front-loaded with the primary purpose and efficiently conveys complex conditional behavior without unnecessary wording.

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 (14 parameters, conditional execution), the description adequately covers the essential behavioral branches: synchronous save with re-analysis, upload-URL return, and follow-up via finish_data_spec_update. It does not detail return structures beyond 'upload URL(s)', but in the absence of an output schema and with 100% schema coverage, this is sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that supplying replacement file parameters (e.g., formatFileName) triggers the upload URL flow, and it clarifies partial update semantics. This contextualizes parameter usage beyond the schema without duplicating it.

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: 'Change an existing data spec's configuration.' This is a specific verb+resource (change + data spec configuration), and it distinguishes itself from siblings like delete_data_spec and the follow-up finish_data_spec_update by explaining the two-phase upload flow. The purpose is unambiguous and well-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 explains when the tool runs synchronously versus when it returns upload URLs, and directs the caller to call finish_data_spec_update after uploading. This gives clear when/when-not guidance and references an alternative tool. The phrase 'Only pass fields you want to change' further clarifies intended usage.

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