mcp-server

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

Adds important context beyond annotations: all requests are POST only, OAuth authentication is automatic, billing mutations are not available via MCP, and response shape varies (raw response or whole body). This enriches the destructiveHint/readOnlyHint annotations without contradicting 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?

Long but densely packed with necessary information–every sentence earns its place. The fallback tool's complexity justifies the length, and the text is well-structured with examples and explicit exclusions, front-loaded with the core purpose.

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

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

Given the tool's complexity, the description is remarkably complete. It covers authentication, HTTP method, workspace scoping, unsupported actions, Iceberg exception, return value conventions, and points to the OpenAPI spec for field details. The output schema exists, so return-value details are adequately supplemented.

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 cover the basics, but the tool description goes much deeper: it explains path format with an example, clarifies action usage, and gives detailed guidance on workspaceId inclusion/omission. It also demonstrates how to structure params for the Iceberg proxy, adding significant semantic value beyond the schema.

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

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

Clearly states it is a fallback/escape hatch for DPF API actions without a dedicated tool. The verb 'call' and resource 'DPF API action' are specific, and it explicitly contrasts with the dedicated sibling tools by saying 'ALWAYS prefer a dedicated tool when one 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?

Provides explicit when-to-use vs when-not-to-use guidance, naming many dedicated tools and stating to prefer them. Includes concrete examples (credits balance, new actions) and rules for workspaceId (include for workspace-scoped, omit for account-level) plus an exception for Iceberg endpoints.

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

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

The annotations are all false, providing no hints about read-only, destructiveness, or idempotency. The description does not disclose side effects, confirmation, or what happens after the message is sent. It only mentions lack of authentication, but this is more of a prerequisite than a behavior. Transparency is limited.

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, with one main sentence followed by two short clauses. No unnecessary information is included, and it is easy to read.

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

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

No output schema is present, so return values are not expected. However, the description does not explain what happens after sending (e.g., confirmation, response time) or the meaning of the reason enum values. Given the low parameter coverage and lack of behavioral details, the description is incomplete for full context.

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

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

Schema coverage is only 25% (only email has a description). The other parameters (name, reason, message) lack any semantic explanation beyond their types. The enum for reason is self-explanatory, but its allowed values are not elaborated. Overall, parameter meanings are poorly specified.

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: sending a message to the DPF team, and enumerates specific use cases (demo request, licensing, issue, feature). This is specific and distinguishable from sibling 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 practical usage instructions: no authentication required and a directive to always ask for the user's email if not already provided. It does not explicitly mention when not to use the tool, but the guidance is sufficient for most 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 (readOnlyHint: false, idempotentHint: false) communicate the non-idempotent write semantics. The description adds the ownership context, which is a useful behavioral trait. However, it stops short of disclosing edge cases like duplicate name errors or quota limits. The addition is decent but not deep.

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

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

Two succinct sentences with zero fluff. The first states the action and ownership; the second conveys a critical usage condition. Both sentences are information-dense and earn their place in the description.

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 2-parameter tool with an output schema and simple semantics, the description covers the essentials: action, ownership, and the primary use case condition. Exposing failure modes (e.g., duplicate names) would push it higher, but the current scope is well-handled and unimpeded by missing context.

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

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

Schema description coverage is 100% (both 'name' and 'description' fields are documented in the schema). The description adds no parameter-level semantics, but given the full schema coverage, the baseline of 3 is the correct score per the rubric.

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+resource pairing ('Create a new workspace') and clarifies ownership ('owned by the authenticated user'). It's clear what the tool does, though it doesn't explicitly differentiate from siblings (not that any overlap is apparent).

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 instruction 'Use this if list_my_workspaces returns none' provides an explicit when-to-use trigger and directs the agent to a related sibling tool. This is exactly the kind of concrete conditional guidance agents need and is a best-in-class example of usage context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the bar for added context is met. The phrase 'and its associated configuration' adds genuine behavioral context about cascading effects not present in annotations. No contradiction between description and annotations.

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

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

A single, front-loaded sentence with zero filler. Every word earns its place - 'permanently' carries the destructive weight, and 'and its associated configuration' adds scope. No redundancy with the title or schema.

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 2-parameter mutation tool with a solid annotation set and an output schema, the description covers the essentials: what happens (delete) and scope (associated configuration). Slightly more color on the return value or edge cases (e.g., deleting a spec in use) would elevate it further.

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

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

Schema coverage is 100%, with both specName and workspaceId already well-described in the schema itself. The description adds no extra parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('delete') with a clear resource ('data spec') and scope ('associated configuration'). The word 'permanently' unambiguously signals the destructive, irreversible nature of the operation, distinguishing it from siblings like update_data_spec or manage_connection.

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?

Usage is implied by the name/description - an agent would know this is the action for removing a data spec. However, no explicit when/when-not guidance is given, no alternatives are named, and there's no mention of prerequisites (e.g., cannot delete if in use). Adequate but minimal.

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 contradicts the idempotentHint annotation by stating that calling again re-attempts starting the job, implying non-idempotent behavior despite the annotation saying it is idempotent. This is a significant contradiction.

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

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

The description is two sentences, front-loaded with the main action and followed by crucial usage warnings. 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?

Given the tool's moderate complexity, the description covers the execution flow, timeout behavior, and provides the correct fallback (get_status). It does not need to explain output schema, which exists separately.

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 (jobId, specName, workspaceId), and the description adds minimal extra meaning beyond reiterating that jobId comes from run_data_job. Baseline of 3 is appropriate.

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

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

The description clearly states the tool starts processing and waits for completion or failure, and explicitly distinguishes it from related tools like run_data_job and get_status by specifying it should be called after uploading and not for polling.

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 gives explicit when-to-use (after uploading) and when-not-to-use (not for polling after timeout) instructions, and names the alternative (get_status), making usage guidelines very 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 directly contradicts the annotation idempotentHint: true. It warns 'do NOT call this tool again just to keep checking — that re-attempts starting analysis,' implying repeated calls have a side effect and do not return a cached/terminal result. This undermines the idempotency annotation and is a serious consistency problem.

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 focused sentences and immediately gives the required trigger, the behavior, and the critical warning. Every sentence earns its place and the most important actionable information is front-loaded.

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

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

For a tool with a rich input schema and output schema, the description covers the necessary operational context: after which step to call it, what it waits for, what happens on timeout, why re-calling is wrong, and what to use instead. No essential behavior is left unexplained for the agent to invoke it safely.

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%, and each parameter already has a meaningful description (e.g., 'specId returned by onboard_data_source', 'loadSampleData ... default true'). The tool description adds some usage context around the parameters but does not need to compensate for missing schema info.

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 specific role: 'Call after uploading the file(s) returned by onboard_data_source — kicks off AI analysis and waits until the spec reaches "ready" or "failed"'. This distinguishes it from the sibling onboarding step and from status-polling tools like 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?

The description explicitly says when to call it ('after uploading the file(s) returned by onboard_data_source') and provides an explicit alternative: 'Poll with get_status (specId) instead until it reaches a terminal status.' It also warns against repeated calls, making the usage boundary very 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?

It reveals important non-obvious behaviors beyond the annotations: that it waits for the spec to reach 'ready' or 'failed', may return early with timedOut: true, and that calling it again re-attempts analysis rather than simply querying status. This is highly valuable because the annotations only indicate mutability and non-idempotency without 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 compact and front-loaded: it starts with the exact invocation context, then explains behavior, timeout handling, and the correct polling alternative. Every sentence carries meaningful operational guidance with no wasted words.

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

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

For a tool with five parameters, a complete output schema, and important orchestration side effects, the description covers the critical workflow context: when to call, what it does, how long it may take, how timeouts are signaled, and how to handle them. It is fully sufficient for an agent to invoke the tool safely and correctly.

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

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

The input schema already provides 100% parameter descriptions, so the baseline is 3. The tool description itself does not add parameter-level detail beyond referencing specId and the returned files, but no additional clarification is necessary given the schema richness.

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

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

The description clearly states the tool's action: it starts AI analysis after a spec upload and waits for a terminal status. It also distinguishes itself from sibling tools like update_data_spec and get_status by framing it as 'step 2' and explicitly relegating status checking to 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?

The description explicitly says to call it after uploading files returned by update_data_spec, warns against re-invoking the tool on timeout, and instructs using get_status instead. This gives strong when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is safe to poll repeatedly. The description adds behavioral context by naming the expected resolution states and the workflow that transitions from spec status to job status. It does not discuss rate limits or pagination, but for a poll tool this is not a significant gap.

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 sentences, front-loaded with the main purpose, and every sentence adds necessary information. No filler or redundancy; it balances specificity with brevity perfectly.

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 polling tool with an output schema available, the description covers both modes of operation, the exact trigger points, and the parameter usage. It is complete enough for an agent to invoke correctly without additional context, especially given the annotations already convey 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 coverage is 100% with descriptions for each param, but the description enriches semantics by explaining the distinct use of specId and jobId, their mutual exclusivity, and the default behavior for workspaceId. It also connects the parameters to the broader workflow, ensuring the agent selects the correct one based on context.

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

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

The description clearly states it polls the status of two distinct resources: a data spec's own process (schema inference + code generation) and a data-load job. It specifies the terminal states ('ready'/'failed' and 'complete'/'failed') and ties them to the relevant identifiers, distinguishing from sibling tools by the unique workflow involving start-analysis and lastJobId.

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 explains when to use: right after create-spec/update-spec + start-analysis, poll by specId; once 'ready', use the response's lastJobId to poll the data-load job by jobId. It also states the required exclusivity of specId/jobId, preventing incorrect invocation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description need not repeat safety. It adds useful behavioral context: pagination defaults (25/page, max 100, newest first), use of nextCursor, and the important semantic distinction that specs are not tables. Does not contradict annotations.

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

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

Two paragraphs; the first is a direct action statement with resource options and pagination; the second clarifies a common misapplication. Every sentence adds necessary information, no fluff, and the key usage 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 dual-resource list tool with pagination and a frequent misuse case, the description covers all essentials: what it lists, page size/cursor mechanics, delineation from table lists, and a pointer to get_status. Given the detailed output schema exists, not describing return format is acceptable; the description is complete.

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

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

Schema coverage is 100% as all parameters have descriptions, so baseline is 3. The description adds value by explaining the resource enum meaning (specs vs jobs), the pagination behavior with cursor, and the workspaceId default, which enriches interpretation beyond the bare schema.

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

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

The description clearly states the tool lists either data specs (parsing + mapping rule sets) or data jobs, specifying the resource parameter values. It distinguishes from siblings by explicitly naming get_status for polling and submit_query for table queries, making the purpose unambiguous.

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

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

Provides explicit when-to-use guidance: for listing specs or jobs, and when-not-to-use: 'NOT a table listing' and directs users to submit_query with SHOW TABLES for actual table existence. Also mentions polling with get_status for specific spec status, covering alternatives and exclusions.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds meaningful context by specifying the access scope (authenticated user), the universal inclusion of workspaces, and the inclusion of permission information, which goes beyond the annotations.

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

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

The description is a single well-structured sentence that is front-loaded with the core action and resource. It contains no filler or redundant information.

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

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

This is a simple zero-parameter read tool with strong annotations and an output schema. The description fully covers the tool's behavior and access scope without needing to explain return values or parameters.

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 no parameters, so the baseline is 4. There is nothing more needed beyond the schema, and the description accurately reflects the zero-parameter interface.

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 a clear resource ('every workspace the authenticated user has access to'), and it adds the useful detail that permissions are included per workspace. This clearly distinguishes the tool from sibling tools like list_data and 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?

The description clearly frames when the tool should be used: to view all workspaces available to the authenticated user and their permissions. It does not explicitly name alternatives or exclusions, but its resource scope is unambiguous given the sibling tool list.

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

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

Annotations indicate readOnlyHint: true and idempotentHint: true. The description adds substantial context: it never performs actions, never asks for a password, and emphasizes the risk of password transcripts. This aligns with annotations and enriches behavioral understanding beyond structured data.

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 lengthy but each section adds necessary detail for safe usage. The action list is well-structured. While slightly verbose, it avoids redundancy and front-loads the critical safety information about password handling.

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

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

Given the complexity (6 parameters, 5 actions) and absence of an output schema, the description fully documents behavior, parameter constraints, and safety considerations. It provides complete guidance for an agent to correctly invoke the tool without additional context.

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

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

Schema coverage is 67%, but the description explains each action's parameter requirements in detail (e.g., 'verify' requires otp, 'register' requires firstName, lastName, termsAccepted, and that termsAccepted must be true only after explicit consent). This goes beyond schema descriptions and clarifies conditional usage.

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 'Returns instructions' for specific account actions (signup, verify, resend, forgot-password, reset-password) and explicitly contrasts with performing actions itself. It distinguishes itself from siblings by focusing solely on account management instructions, which is unique among the listed tools.

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

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

Explicitly instructs when to use the tool (handing commands to the user) and when not to (do not run commands even with shell access, due to password exposure). Per-action usage requirements are detailed, such as requiring termsAccepted only after explicit user agreement, and verifying OTP formats.

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 behavioral nuances beyond annotations: create generates a keypair and returns a public key for SFTP; for AWS S3 it returns a trustPolicy and dpfPrincipalId. It also clarifies that both types must pass test before a trigger can work. This is substantial behavioral disclosure not present in annotations (which only say destructive=true). No contradiction.

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

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

The description is longer but information-dense. It packs a lot: two types, four actions, setup prerequisites, and alternative tool. The structure is logical (overview, type-specific flows, usage rule). Could be slightly tightened but the length is justified by complexity. Front-loaded with the core action 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 complex tool with two types and multi-step setup, this description covers: the actions, per-type requirements, the test gate, and the recommended alternative tool (setup_scheduled_pull). It even explains what the create action returns (public key, trustPolicy) which is critical. An output schema exists, so return formats are elsewhere covered. Very complete.

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

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

Schema covers 100% of params with descriptions, so baseline is 3. The description adds contextual meaning: roleArn is aws_s3 only, hostname/username are sftp only, connectionId needed for test/delete, workspaceId defaults to sole workspace. This clarifies which params apply to which action/type, which the schema does not. Solid upgrade over schema.

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

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

The description clearly states the tool creates, lists, tests, or deletes workspace connections, explicitly names the two supported types (sftp, aws_s3), and distinguishes itself from the sibling tool setup_scheduled_pull by advising to prefer that tool for first-time scheduled pulls.

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 to use this tool versus setup_scheduled_pull, and provides per-type setup steps (install public key for SFTP, update IAM role for S3) and the test-before-use requirement. It also says what's required for each action (create requires certain fields, test/delete require connectionId).

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 readOnlyHint=false, destructiveHint=true, openWorldHint=true. The description adds rich context: for s3 it notes the 5000-object listing limit and warns to relay the `warnings` array and suggest an S3 lifecycle rule; for dedupe it details what happens when the same file reappears; for run-now it explains status transitions to success/failed/no-files. It also warns that preRules/postRules compile server-side (never pass raw code). Minor deduction: some behaviors (e.g., what happens on delete) are not enumerated, but the description goes well beyond the structured 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 substantial but every section serves a purpose: lead verbs, per-type paragraphs, an 'IMPORTANT' callout for the most common mistake, a bulleted list of trigger types, and a final 'after firing' note. Formatting with newlines and bold text improves scannability without bloat.

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 19-parameter, 7-action, 4-type tool, the description covers all operational contexts: create vs. update vs. run-history, prerequisites (connection tested, spec analyzed, table-source spec for spec_success/schedule), type-specific requirements (s3Bucket for aws_s3), and monitoring via run-history. The output schema's existence lowers the need to document return values, and the description still mentions `filesPulled`/`message` fields. Nothing critical left unexplained 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 already 100%, so the baseline is 3. But the description goes further: it explains the `dedupe` parameter's real-world consequences (silently skipped re-uploads or reloaded files), documents connection prerequisites, clarifies the relationship between type and connection, and explains the `warnings` array in the response, adding meaning beyond the schema's prose.

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 ('Create, list, update, delete, or fire') and resource ('a workspace job trigger') and immediately distinguishes four trigger types (sftp/aws_s3, spec_success, schedule) with concrete examples ('run this after the customers load finishes'). This clearly differentiates from siblings like setup_scheduled_pull and manage_connection by naming them where relevant.

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

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

Explicit guidance is given throughout: 'prefer setup_scheduled_pull' for first-time scheduled pulls, 'Prefer spec_success when... prefer schedule when... ask if genuinely ambiguous,' and the special constraint that spec_success/schedule only target table-source specs. This goes beyond vague alternatives to provide decision rules with concrete user-phrasing examples.

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

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

With annotations all false, the description carries the full burden of explaining side effects. It details what is created, what is returned (upload URLs or empty files array), how the SQL query is generated for tables mode, and the real-world consequences (credits charged, stale summaries) of choosing the wrong autoRefresh value.

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

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

The description is lengthy, but the complexity of the tool (15 params, two modes) justifies the detail. It front-loads the core purpose and organizes related information together. Could potentially be tightened with bullet formatting, but every sentence contributes useful guidance.

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 15 parameters, nested objects, enums, and an output schema, the description covers all major decision points, return flows, and next steps. It explains what to do after the call, what to expect in different sourceType/targetOption combinations, and when to ask the user for clarification.

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?

Despite 100% schema coverage, the description adds substantial meaning to parameters like autoRefresh (explains the three options and when each is appropriate), merge (clarifies behavior for null columns), and targetOption. It provides decision guidance that goes far beyond the schema's field 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 is the first step of onboarding a data source, creating a data spec and returning presigned upload URLs. It distinguishes itself from sibling tools like finish_data_source_onboarding by explicitly labeling itself as 'step 1' and describing the follow-up flow.

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

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

The description provides explicit guidance on when to use sourceType 'file' vs 'tables', with concrete examples ('build me a daily summary of the customers table'). It instructs the agent to ask the user for autoRefresh rather than inferring from existing workspace state, and warns about the costs of wrong choices.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, but the description adds important behavioral context: it creates a job, returns presigned upload URLs, and requires a subsequent call to finish_data_job. It also discloses the side effect of creating a redundant job if misused. This goes beyond the annotations, though it doesn't detail the upload process or job lifecycle fully.

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 first sentence and a warning paragraph. It is slightly verbose but every sentence adds value, explaining the workflow and the redundancy pitfall. The front-loading is good, with the core purpose stated first.

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

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

Given the tool's complexity (multi-step workflow, potential redundancy), the description covers the key points: what it does, how to proceed, and when to avoid it. It doesn't explain the upload instructions or job completion details, but the output schema likely covers return values, and the description points to finish_data_job for the next step. It is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context about the relationship between specName and fileNames (processing files through a configured spec) and the workflow (upload then finish), but it doesn't add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'First step of processing new data files through an already-configured data spec: creates a job and returns presigned upload URL(s) for each file.' It specifies the verb (creates), the resource (job), and the scope (for new data files), and distinguishes it from sibling tools like finish_data_job and onboard_data_source.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It warns against calling this tool right after onboarding or spec update unless loadSampleData was false, and explains the alternative (using the returned lastJobId). It also clarifies the intended use case: 'Only use this for files beyond the initial sample.'

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 behaviors beyond annotations: it reuses a matching connection if one exists, otherwise creates one, tests it, and only creates a trigger if the test passes. It notes that no trigger is created on failure and that re-running picks up where it left off. It also explains consequences of dedupe true/false. This goes well beyond the minimal readOnly/destructive hints.

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

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

The description is dense but every sentence contributes value: the workflow, parameter selection rule, alternative guidance, failure behavior, and exclusion clause. It is appropriately sized for an 11-parameter tool and front-loaded with the primary purpose.

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

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

Given the tool's complexity (11 params, nested frequency object, output schema exists), the description covers the end-to-end workflow, parameter selection constraints, failure handling, and alternatives. It references onboard_data_source for the spec prerequisite. The presence of an output schema makes return-value documentation unnecessary.

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 description adds crucial parameter semantics not fully captured by the schema: exactly one of hostname or roleArn must be provided, and s3Bucket is required with roleArn. It also clarifies the SFTP vs aws_s3 pull modes. Schema coverage is 100%, so this extra information elevates the score above the baseline of 3.

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

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

The description clearly states the tool's purpose with a specific verb ('Set up a scheduled SFTP or S3 pull') and identifies the resource ('into an existing data spec'). It further distinguishes itself from siblings by explicitly saying 'Use this instead of calling manage_connection + manage_trigger yourself' and referencing manage_trigger with type 'schedule' or 'spec_success' for a different use case.

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

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

The description provides explicit when-to-use guidance (first-time setup for scheduled external pulls), when-not-to-use guidance (schedule/spec_success on tables already in the workspace should use manage_trigger instead), and alternatives (manage_connection + manage_trigger, manage_trigger). It also explains what to do if the connection test fails (ask user to finish setup and re-run).

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses significant behavioral traits: rejection of qualified table references, rejection of engine-introspection functions, the fact that BLOB columns are very likely HLL sketches, and the specific decoding functions. It also clarifies that results should not be embedded as static snapshots without user consultation. This adds substantial context 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 long but information-dense. The first sentence is concise and clear, but subsequent paragraphs contain essential caveats and branching logic. While every sentence earns its place, the length is substantial; however, given the complexity of the tool (query execution, HLL sketches, dashboard context), it is appropriately structured and not padded.

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

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

Despite having an output schema, the description still adds critical context: it explains rejection rules, HLL sketch handling, and the decision process for static vs. live dashboards. It covers edge cases and clarifies what to do when results are for a dashboard, making it complete for a complex query tool. The presence of an output schema does not substitute for these behavioral and contextual 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?

The schema already covers 100% of the parameters with descriptions (sql and workspaceId). The description does not add new meaning to the parameters themselves, aside from providing example SQL syntax in the schema description. The behavioral guidance about what sql can contain is more about tool behavior than parameter semantics, so no significant extra value is added beyond the schema.

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

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

The description clearly states the tool's function: 'Run a SQL query against the Iceberg tables loaded into a workspace.' It uses a specific verb (Run) and resource (SQL query on workspace tables), and distinguishes itself from sibling list_data by noting that SHOW TABLES is authoritative for live tables, not list_data. This provides clear differentiation from related 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?

Explicit usage context is provided: it advises using SHOW TABLES to discover tables, warns against qualified references and engine-introspection functions, and explains when to ask users about static vs. live HTML pages. It also mentions an alternative (list_data) and instructs to read a resource for live dashboards, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false latently; the description adds real behavioral detail: it re-runs AI analysis by default, returns final status synchronously in one path, and requires a follow-up call in the other. This goes beyond the annotations, which lack such nuance. No contradiction with annotations.

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

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

The main body is two dense sentences that front-load the key distinction (sync vs. async) and end with a clear 'only pass the fields you want to change' rule. The additionalPrompt field description is verbose, but it carries critical guidance about not restating default behavior drifted into standing instructions—arguably necessary for that parameter. Overall it is structured and efficient.

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

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

With 14 parameters need conditional guidance; the description covers the two top-level modesusing `sourceType`, points to the required follow-up tool (finish_data_spec_update), and the schema covers param types/enums. The output schema exists (not shown) so return-value details are not needed. Adds important context about side effects like re-running AI analysis and loadSampleData interplay, making the description complete enough for safe invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter semantics (e.g., formatFileName implies the async path, targetSchemaFileName is required when targetOption is 'target-schema-file', omitted fields keep current values) and warns about additionalPrompt misuse. This clearly enhances the schema's per-field definitions.

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 changes an existing data spec ('Change an existing data spec'), specifying the resource and action. It distinguishes from siblings like finish_data_spec_update and delete_data_spec by explaining the two distinct paths (synchronous save vs. presigned-URL upload). This is a specific verb+resource with clear differentiation.

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

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

The description explicitly explains when to use the synchronous path (no replacement file names) vs. the upload path (when a sample/format/target-schema file name is given), and directs the agent to call finish_data_spec_update after upload. It also clarifies that omitted fields keep current values, guiding correct invocation. This is strong, explicit usage guidance.

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