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

With no annotations provided, the description carries the full burden and does a solid job: it declares this is a write tool, states authorization requirements, and discloses the all-or-nothing validation behavior ('if any errors, nothing is created'). It stops short of explaining whether existing resources are overwritten or merged, but covers the most critical behavioral traits.

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: action, access requirement, format, and validation behavior each get one clear sentence. The Args section adds useful structure without bloat, and every sentence earns its place.

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

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

For a complex bulk operation, the description covers authorization, format, atomic validation, and the payload's major sections, and an output schema exists for return-value details. The main gap is the lack of detail about what happens to existing resources on import, but the guide reference fills much of this.

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 is nearly empty (an object with additionalProperties: true), so the description must compensate. It does name the payload format (JSON v2), enumerates the expected sections (version, connections, uploads, pipelines, transformations), and points to AI_IMPORT_GUIDE.md for details. This is meaningful guidance, though the description could be more self-contained about exact payload requirements.

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

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

The description opens with a specific verb and resource set: 'Bulk-import connections, uploads, pipelines, and transformations in one call.' This clearly differentiates the tool from singular siblings like create_connection and create_pipeline. An agent immediately understands the scope and one-call nature.

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

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

The description states the key precondition: write access must be granted via --allow-write or OAuth consent, and read-only sessions refuse the call. It also implies the use case by contrasting with single-create tools, though it does not explicitly name alternatives or say 'use create_* for single imports.'

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 no annotations provided, the description carries the full burden of behavioral disclosure. It discloses a key trait: no execution, and mentions the compilation process (resolving Jinja, ref(), source()). However, it does not describe what the output looks like (though an output schema exists) or whether there are any side effects. More context, such as a dry-run nature, would enhance transparency.

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 the primary information front-loaded in the first sentence. The Args section is somewhat redundant but does not detract. Every sentence earns its place, and the structure is clean.

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 has only one parameter and an output schema, the description covers the essential behavior. It lacks explicit usage guidance but is otherwise complete for a simple compilation tool. The output schema likely details return values, so the description need not elaborate.

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 zero description coverage, so the description's 'The transformation to compile' adds minimal meaning beyond the parameter name. It clarifies the parameter's role but doesn't explain how to obtain a transformation_id or any constraints. The description barely compensates for the lack of schema documentation.

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 'compile' on a 'dbt transformation' and explicitly specifies that it resolves Jinja, ref(), and source() with no execution. This distinguishes it from siblings like preview_transformation and trigger_transformation, 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?

The description conveys the context that this tool performs compilation only and does not execute, which implies it is for validation rather than running. However, it does not explicitly state when to use this tool over preview_transformation or trigger_transformation, nor does it list exclusions or alternatives. The context is clear but not fully explicit.

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 no annotations, the description must carry behavioral disclosure. It does disclose the write-access prerequisite and that read-only sessions refuse the operation. However, it omits other behavioral traits such as return value expectations (despite an output schema), potential side effects, or failure modes for invalid config. Coverage is partial.

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

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

The description is tightly structured: a one-sentence purpose, a critical permission note front-loaded, then a clean arg list. No wasted words; every sentence earns its place. The write-access caveat is placed before the args, ensuring the agent sees it 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?

Output schema exists, so return values need no explanation. However, the description does not address how config depends on connection_type (which could vary significantly), nor does it point to get_connection_types for a list of valid types. The open-ended config object with additionalProperties true creates ambiguity that the description only partially mitigates.

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

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

Schema coverage is 0%, so the description must compensate. It provides meaningful explanations for all three parameters: name ('human-readable'), connection_type ('one of supported types' with examples), and config ('connection-specific configuration' with host, port, credentials). This adds value beyond the bare schema, though it could list supported types or link to get_connection_types for completeness.

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

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

States a specific verb and resource: 'Create a new data connection.' This clearly distinguishes it from sibling creation tools like create_pipeline and create_transformation. The purpose is unambiguous and directly actionable.

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 no guidance on when to use this tool versus alternatives such as preview_connection or get_connection. It only mentions permission requirements (write access) but does not contextualize selection among siblings or note exclusions. The agent must infer usage from the name alone.

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 no annotations supplied, the description carries the burden and discloses the critical authorization behavior and that read-only sessions will refuse the call. It does not discuss side effects or duplicate handling, but 'create' and the access warning cover the main non-obvious behavior.

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

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

The description leads with the purpose, adds one necessary access-control note, and then uses a compact Args block. Every sentence contributes; no filler or duplication beyond the useful args 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 create operation with an output schema, this covers the operation, required access mode, and all argument meanings. The only gap is a brief pointer to sibling tools like trigger_pipeline when the intent is to execute rather than create.

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 four parameters are listed, and command gains real value by enumerating allowed dbt commands ('run', 'build', 'test', 'seed', 'snapshot', 'compile'). However, name, destination_connection_id, and description mostly restate schema titles/defaults rather than adding deeper 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 first sentence states a specific verb ('Create') and resource ('new pipeline') and clarifies 'dbt transform orchestration,' distinguishing it from siblings like create_transformation. The purpose is unambiguous.

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

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

It explicitly frames this as a write tool, states it is available only with --allow-write or OAuth write consent, and warns read-only sessions refuse it. It gives clear access context but does not name alternative tools or when to prefer triggering an existing pipeline.

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?

No annotations are provided, so the description must carry the full burden. It discloses the write-only behavior and refusal in read-only sessions, which is a key behavioral trait. However, it does not disclose other behaviors such as behavior on duplicate names, potential error conditions, or any side effects beyond creation. Given the absence of annotations, this is a partial disclosure.

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 concise paragraph followed by a clearly formatted Args list. The purpose is front-loaded in the first sentence, the write-access caveat is placed next, and each parameter is given a single line. There is no redundancy; every sentence earns its place.

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

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

The tool has 5 parameters, an output schema, and no annotations. The description covers the write-access constraint, all parameter semantics, and the default schema. It does not describe the return value, but since an output schema exists, that is acceptable per the rubric. It also doesn't mention error handling, but for a creation tool this is a minor gap. Overall, it is sufficiently complete for an agent to call it 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 provides only titles and defaults; there are no per-parameter descriptions. The description compensates fully: it explains the name validation pattern, the SQL body content (dbt-compatible with ref(), source(), Jinja), the allowed materialization values, and the default schema. This is far more than the schema offers, so it adds significant value.

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

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

The description opens with a specific verb+resource: 'Create a new dbt SQL transformation.' It clearly distinguishes from sibling creation tools (create_connection, create_upload, create_pipeline) by naming the resource type. The write-access caveat is contextual but not confusing.

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

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

The description explicitly states the write-access requirement and that read-only sessions refuse the call, which is a clear usage context. However, it does not mention alternative tools for other operations (e.g., compile_transformation) or explicitly state when not to use it beyond the write-access condition. Thus, it has clear context but no 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?

With no annotations, the description carries the full burden. It explicitly discloses that this is a write operation and will be refused in read-only sessions, which is important behavioral context. However, it does not mention what happens on success (e.g., whether the upload is queued or run immediately), or any other side effects beyond creation.

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 well-structured: a one-line definition, a permission note, and a clean args list. Every sentence earns its place, and the most critical information (purpose and write restriction) 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 creation tool with an output schema (which presumably describes the return), the description is quite complete. It covers purpose, permissions, and all parameters. The only notable gap is lack of information about the job's lifecycle (e.g., whether it starts immediately or is asynchronous), but this is partly mitigated by the output schema.

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

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

The schema description coverage is 0%, so the description must compensate. It does this fully by listing each argument with a meaningful explanation: name, source/destination connection IDs, optional dlt config with examples, and optional description. This adds significant value beyond the raw schema types.

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 'Create a new upload (extract + load job)' with a specific verb and resource, and clarifies what an upload is. However, it does not explicitly differentiate from sibling tools like trigger_upload, though the create vs. trigger distinction is implied by the naming.

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 a clear condition for use: it requires write access, and read-only sessions will refuse it. This is a useful usage guideline, but it does not mention when to prefer this tool over alternatives like create_pipeline or trigger_upload, leaving some selection ambiguity.

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 no annotations provided, the description carries the burden of behavioral disclosure. 'Get' implies a read-only retrieval, but the description does not state whether the result is static, cached, or dependent on API state, nor does it clarify what the 5 tiers represent beyond a vague capability stack.

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 front-loaded sentence with the key action and resource immediately visible. The second clause 'describes what the API can do' is mildly redundant but does not seriously hurt 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?

For a simple no-parameter metadata tool, the description is mostly adequate, but it lacks explicit guidance on when to use it and what the returned capability stack contains. The presence of an output schema lessens the need to document return values, so this is a minor gap rather than a critical one.

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

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

The tool has zero parameters, so the schema already fully documents the invocation surface. The baseline of 4 applies, and the description adds no unnecessary parameter information.

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

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

The description names a clear verb and resource: 'Get the 5-tier agent capability stack.' It is specific enough to distinguish this from the pipeline, connection, and transformation siblings, though the trailing 'describes what the API can do' adds little precision.

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?

There is no guidance about when to call this tool versus any alternative. The use case is only implied as an informational/capability lookup, and no exclusions or alternatives are mentioned.

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?

No annotations are provided, so the description bears full burden for behavioral disclosure. It only says 'Get details', which implies a read operation, but it does not disclose authentication requirements, rate limits, performance implications, or whether the operation is safe. The minimal description adds little beyond the obvious.

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 with two sentences, front-loading the core purpose. Every word earns its place, and the structured 'Args:' format is clear and efficient.

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

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

Given the tool is simple with one parameter and an output schema exists, the description covers the basic purpose and parameter. However, it lacks usage guidelines and behavioral context, which are gaps for completeness. It is minimally adequate but not comprehensive.

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

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

Schema description coverage is 0%, so the description must compensate. It provides a basic description for entry_id ('The catalog entry ID.'), adding meaning beyond the schema's property name. For a single integer parameter, this is adequate but minimal.

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

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

The description clearly states the verb 'Get' and the resource 'specific catalog entry', distinguishing it from sibling tools like 'list_catalog' which lists all entries. It explicitly indicates this tool is for retrieving details of one entry.

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

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

The description implies use when needing details of a single entry, but it does not explicitly state when to use this tool versus alternatives like 'list_catalog'. No when-not or exclusion criteria are provided.

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?

No annotations are present, so the description carries the full burden of behavioral disclosure. 'Get details' suggests a read operation, but it does not state whether the call is safe/idempotent, what error behaviors exist, or what level of detail is returned beyond the output 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 a single focused sentence with no filler and the key operation is stated up front. Every word contributes to the meaning.

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 getter with one required integer parameter and an output schema, the description provides the minimum viable call guidance. However, it does not disambiguate against several closely related connection tools, so an agent may not know if this is the right tool for 'details' versus introspect_connection or preview_connection.

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

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

Schema coverage is 0%, so the description must compensate for the parameter docs. It adds only 'by ID,' which essentially restates the parameter name connection_id and does not explain how to obtain the ID, accepted value ranges, or behavior for invalid IDs.

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

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

The description states a clear verb and resource: 'Get details of a specific connection by ID.' It conveys a targeted lookup and distinguishes from listing tools, but it does not explicitly differentiate from connection-related siblings like introspect_connection or preview_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?

No guidance is given on when to use this tool versus the many related siblings such as list_connections, introspect_connection, or query_connection. The phrase 'specific connection by ID' implies a use case, but there are no explicit when/when-not criteria or alternatives.

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

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

With no annotations, the description carries the full burden. 'List all supported connection types' strongly implies a read-only enumeration, and it does disclose the returned information. However, it does not explicitly state that it is non-mutating, requires no special permissions, or describe any behavioral constraints beyond the listing.

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 front-loads the action and result. Every word contributes meaning, and there is no wasted 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 low complexity, zero parameters, and presence of an output schema, the description is nearly complete. It states what is returned (types and config schemas) and that all types are included, though it could slightly benefit from noting that this is a static catalog or that no connection context is required.

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

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

The tool has zero parameters, so the baseline is 4. The description reinforces that no inputs are needed by saying it lists 'all' supported types, which adds no ambiguity. No parameter-level documentation is required.

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 ('all supported connection types') and further clarifies that it returns their config schemas. This clearly differentiates it from siblings like list_connections (actual connection instances) and get_connection (single 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?

The description implies the tool is for discovering available connection types and their config schemas, but it does not explicitly state when to use it over alternatives or mention exclusions. The intended use is clear, but no direct guidance is provided.

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?

No annotations are provided, and the description only says 'Get details' without disclosing what details are returned, any side effects, permissions, or error conditions. For a read operation, more transparency is expected.

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 exceptionally concise with two short sentences and no extraneous information. Every word serves a 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?

Despite an output schema existing, the description is very brief and does not indicate what the returned details include, nor does it explain the parameter or tool behavior sufficiently. More context is needed for a self-contained definition.

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 0% description coverage for run_id, but the description adds 'The run ID to look up,' which provides minimal meaning beyond the schema's type and title. More detail on source or format would improve this.

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 gets details of a specific run by ID, with a verb ('Get') and resource ('run details'). It distinguishes from siblings like list_runs (list all) and get_run_logs (logs only).

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?

No guidance is provided on when to use this tool versus alternatives, such as using list_runs to find run IDs or get_run_logs for execution logs. The description lacks 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?

With no annotations, the description should disclose behavioral traits. It only says 'Get the logs', which implies a read operation, but does not confirm idempotency, side effects, or whether the run must be completed. The lack of annotation burden falls entirely on the description, which fails to provide sufficient transparency.

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

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

The description is very short and front-loaded, but it is appropriately sized for a simple one-parameter tool. However, it could be better structured with a separate requirements or return section.

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 output schema exists (though not shown), the description need not explain returns. However, missing context about log format, pagination, or prerequisites (e.g., run status) makes it borderline adequate for a simple tool.

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

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

Schema coverage is 0%, but the description's 'Args' section adds minimal value: 'The run ID whose logs to fetch' essentially restates the parameter name and property title. It does not explain acceptable values, format, or how to obtain the run_id.

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

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

The description states the verb 'Get' and the resource 'logs of a specific run', which is clear and matches the tool name. However, it does not differentiate from sibling tools like 'get_run' or 'list_runs', but the focus on logs is distinct enough.

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?

No guidance is provided on when to use this tool versus alternatives (e.g., 'get_run' or 'list_runs'). There are no prerequisites, exclusions, or use-case 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The verb 'List' clearly indicates a read-only operation with no side effects, which is sufficient for transparency. However, it does not explicitly state that it is non-destructive or that no data is modified. Given the simplicity of a listing operation, this is acceptable but could be more explicit.

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 the main purpose stated in the first sentence and parameters listed in a structured docstring format. Every sentence earns its place, and there is no redundancy. The structure is front-loaded with the core function, making it easy to scan.

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

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

The tool has an output schema, so return values are documented externally. The description covers the essential behavior (listing schemas and tables) and parameters completely. It lacks explicit error-handling or edge-case details (e.g., invalid connection_id), but for a simple introspection tool this is not a critical gap. Overall, it is sufficiently complete for an agent to call 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 0%, meaning the input schema contains no field descriptions. The description compensates by explicitly explaining both parameters: connection_id as 'The connection to introspect' and schema as 'Optional schema name to filter tables'. This fully covers the semantics, including optionality and default behavior, adding significant value beyond the schema.

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

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

The description clearly states a specific verb ('List') and resource ('schemas and tables of a source connection'). This distinguishes it from sibling tools like preview_connection or query_connection, which imply different actions. The purpose is immediately obvious and unambiguous.

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

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

The description implies when to use the tool (to introspect a connection's schema), but it does not explicitly state when not to use it or mention alternatives. Given the sibling tools (preview_connection, query_connection, list_connections), the agent must infer the right choice from context. There is no guidance on exclusions or prerequisites, so usage guidance is adequate but not explicit.

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?

No annotations provided, and the description lacks behavioral details such as whether pagination or rate limits apply, leaving the agent with incomplete information about potential side effects.

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?

Single sentence, front-loaded with the core action, and no extraneous 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?

For a zero-parameter, read-only list tool with an output schema, the description provides sufficient context to use the tool correctly.

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

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

Schema coverage is 100% with zero parameters, so baseline applies; description adds no parameter-specific value but also isn't needed.

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

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

Clearly states action ('List all catalog entries') and specifies the resource ('source tables and dbt models'), effectively distinguishing from sibling tools like get_catalog_entry.

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?

No explicit when-to-use or when-not-to-use guidance, but the purpose is clear enough that an agent would infer standard use for listing catalog entries.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action ('list all connections') without revealing any behavioral traits such as pagination, rate limits, authentication requirements, or whether results are returned in a single response. This is a significant gap for a list operation.

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 is easy to parse. It is appropriately sized for a tool with no parameters, though it could arguably be slightly more informative without becoming verbose.

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 and no parameters, the description lacks any guidance on behavior such as pagination, scoping, or when to use this tool over its siblings. For a list tool in a context with many related operations, this is incomplete.

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

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

The tool has zero parameters, so the schema already documents everything. The description adds no parameter information, but none is needed. Baseline 4 applies because with no params, the description cannot add meaning beyond the schema.

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

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

The description clearly states a specific verb ('list') and resource ('connections'), and the word 'all' distinguishes it from get_connection, which retrieves a single connection. However, it does not explicitly contrast with other list tools like list_uploads or list_pipelines, though those target different resources. Overall the purpose is clear.

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?

No guidance is provided on when to use this tool versus alternatives such as get_connection or preview_connection. The description only says what it does, not when to choose it over siblings. There is no mention of exclusions 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?

No annotations are present, so the description bears full responsibility for behavioral disclosure. It only states 'List all pipelines', which implies a read-only operation but does not confirm idempotency, performance considerations, pagination, or organizational scope (only stated as 'in the organization'). The lack of explicit safety or side-effect information is a gap given zero 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, efficient sentence that front-loads the core action and object. No extraneous words or redundant information. Every word earns its place.

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

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

Given the tool's low complexity (no parameters, simple list) and the presence of an output schema, the description adequately covers the essential purpose. It mentions organizational scope. However, it could briefly note that there is no filtering or that it returns all pipelines, but the output schema likely fills that gap. Minor room for improvement.

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

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

With zero parameters, the schema coverage is 100% and the description does not need to add param-level detail. The description adds no extra meaning beyond the schema, but per rules, 0 parameters earns a baseline of 4. This is appropriate because the tool's behavior is fully captured by its parameterless signature.

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

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

The description clearly states the verb 'List' and the resource 'pipelines' with a clarifying parenthetical '(dbt transform orchestration)'. It distinguishes this tool from siblings like list_runs or list_transformations by explicitly targeting pipelines. No tautology or missing 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?

No guidance is provided on when to use this tool versus alternatives. While the tool name and description imply listing all pipelines, it does not mention when not to use it or suggest alternative tools for filtered or specific pipeline queries. Sibling tools like list_runs and list_transformations exist but no differentiation is given.

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?

No annotations are provided, so the description bears full responsibility. It states the tool lists runs with optional filters, which is typical for a read operation. However, it does not explicitly declare read-only behavior, permissions, or pagination details beyond the limit parameter.

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: a single sentence summarizing purpose followed by a clear list of parameters with explanations. Every sentence adds value, and the structure is easy to scan.

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

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

An output schema exists (not shown), so return values need not be explained. The description covers purpose, all parameters, and filter options. Minor omissions: no mention that the operation is read-only or how results are ordered. Still, it is largely complete for a list 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?

With 0% schema description coverage, the description fully compensates by detailing the meaning of each parameter: target_type values, status values, and limit with default and max. This adds significant value beyond the schema's type 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 that the tool lists pipeline/upload/transformation runs with optional filters. The verb 'list' and resource 'runs' are specific, and the scope distinguishes it from sibling tools like list_pipelines and list_transformations.

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

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

The description explains the filters but does not provide explicit guidance on when to use this tool versus alternatives like get_run or get_run_logs. It is adequate for a listing tool but lacks when-not-to-use information.

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?

No annotations are provided, so the description bears full responsibility. It only states 'List all dbt transformations' without disclosing behavioral traits like pagination, sorting, rate limits, or authentication needs.

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 sentence that contains no superfluous words. It is appropriately front-loaded with the verb and resource.

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 has zero parameters and an output schema, the description is largely sufficient. It clearly states the operation, though it could mention any default ordering or limit if applicable.

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

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

The input schema has zero parameters with 100% coverage, so baseline is 4. The description adds minimal value by confirming the operation takes no arguments, but no further parameter semantics are needed.

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

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

The description uses a specific verb ('List') and resource ('dbt transformations'), clearly stating the action and scope. It distinguishes from sibling tools like list_catalog or list_pipelines by naming the specific resource.

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 such as list_catalog or list_pipelines. There are no exclusions or context about 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?

No annotations are provided, so the description must disclose behavior. It states the tool lists uploads but does not explicitly confirm it is read-only, non-destructive, or describe any side effects, permissions, or rate limits. The description relies on the agent assuming a list operation is safe, which is not explicit.

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, front-loaded sentence that immediately communicates the core purpose. Every word earns its place, 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?

Given the tool has no parameters and an output schema (presumably documenting return values), the description is minimally adequate. However, it lacks usage context among siblings and does not explain behavioral aspects like pagination or ordering. More detail would improve completeness for an agent navigating multiple list tools.

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

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

The input schema has zero parameters, and schema coverage is 100%. According to guidelines, 0 parameters yields a baseline of 4. The description does not need to add parameter information and does not detract from clarity.

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 all uploads and clarifies that uploads are extract+load jobs. It specifies the scope ('in the organization') and the verb 'list', making the purpose unambiguous. Although no sibling tool also lists uploads, the description differentiates from other list tools by defining the resource type.

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?

No guidance is provided on when to use this tool versus alternatives like list_transformations or list_catalog. There is no mention of prerequisites, use cases, or exclusions. The agent is left to infer context from the tool name alone.

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 no annotations, the description carries the transparency burden. It communicates the core read-only preview behavior and the default row limit of 100, but it does not explicitly state that no data is modified, mention permission requirements, or describe error behavior.

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

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

The description is compact and front-loaded with the core purpose, followed by a concise parameter list. Every line adds useful information with no filler or redundancy.

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

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

The output schema covers return shape, and parameter semantics are documented, so a basic call can be made. However, the absence of usage guidance, behavioral caveats, and annotation-backed safety information leaves the description incomplete for a tool with no annotations.

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

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

Schema description coverage is 0%, so the description must compensate, and it does by explaining all four parameters: connection_id, table, schema, and limit. It adds meaning beyond the schema, especially the default value for limit and the optionality of schema, though lacks further format or constraint details.

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 ('Preview') and resource ('first N rows of a table from a source connection'). It does not explicitly distinguish itself from siblings like preview_transformation or query_connection, so it falls short of full sibling 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?

There is no guidance about when to use this tool versus alternatives such as preview_transformation, query_connection, or introspect_connection. No prerequisites, exclusions, or alternative selection criteria are provided.

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?

No annotations provided, so description carries burden. It mentions compilation and execution but does not disclose whether it modifies state, cost implications, or safety for repeated calls. For a preview tool, likely safe but not explicit.

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?

Very concise: two lines plus Args list. Front-loaded with purpose, no redundant 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?

Has output schema so return values are covered externally. Covers main parameters but could mention prerequisites (e.g., transformation must exist). Adequate for a simple preview tool.

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

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

Schema coverage is 0%, but description adds meaning: explains transformation_id as required and limit with default and max. This adds value beyond the schema's type information.

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

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

The description clearly states it compiles and executes a transformation to return preview rows. This distinguishes it from sibling tools like trigger_pipeline (full execution) and list_transformations (listing only).

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?

Implicitly suggests use for previewing without full execution, but does not explicitly state when not to use or direct to alternatives. Lacks explicit usage context compared to sibling tools.

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

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

There are no annotations, so the description itself must carry the safety disclosure; it does so by stating 'read-only' and 'no mutations allowed.' It also communicates that queries must be a single SELECT statement, which is a meaningful behavioral constraint. It does not cover error behavior or limits, but the output schema covers return structure.

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

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

The description is compact and front-loaded, with a clear one-line purpose followed by brief parameter explanations. No filler or redundant restatement of the tool name.

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

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

For a simple two-parameter tool with an output schema, the description covers the action, parameter semantics, and the key read-only/no-mutation behavioral constraint. Nothing essential appears to be missing for an agent to invoke it 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 0%, so the description must compensate, and it does: query is explained as 'A single SELECT statement (no mutations allowed),' which adds a real constraint beyond the schema. connection_id is described as 'The connection to query,' which is somewhat tautological but still orients the agent to the intended resource.

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

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

The description opens with a specific verb and resource: 'Execute a read-only SQL query against a source connection.' The 'read-only' and SELECT framing clearly separates it from mutation-oriented tools. It does not explicitly name sibling alternatives like preview_connection, so it stops short of full sibling 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?

It clearly establishes this tool is for read-only queries and restricts input to 'a single SELECT statement (no mutations allowed),' giving an explicit functional boundary. It does not explicitly tell the agent when to prefer related tools such as preview_connection or introspect_connection, but the context is not misleading.

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 no annotations provided, the description carries the full behavioral burden, and it excels: it discloses write permission requirements, wait timeout behavior, failure returned as a status field rather than an error, and timed_out results. This is exactly the kind of non-obvious runtime behavior an agent needs to know.

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 organized into a short purpose line, a clear permission note, and a labeled Args section. Every sentence provides necessary operational detail, with no filler or redundancy.

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

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

For a tool with only two parameters and an output schema, the description covers all essential context: when execution is permitted, what wait does, how failures surface, and how timeouts behave. An agent has everything it needs to invoke the tool correctly and interpret the response.

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 0% description coverage, but the description manually documents both parameters: pipeline_id as "The pipeline to run" and wait with its blocking behavior, timeout, and result semantics. This fully compensates for the missing schema descriptions and adds meaning well beyond the raw types.

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

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

The description opens with a specific verb and resource: "Trigger a pipeline run (dbt build/run/test)." This clearly identifies the operation and distinguishes it from sibling tools like trigger_transformation and trigger_upload by targeting pipelines specifically.

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

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

The description explicitly states the write-access prerequisite and that read-only sessions will refuse the call, giving clear contextual guidance for when the tool can be used. It does not explicitly name alternative tools or contrast them, but the resource-focused wording makes the intended use 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?

With no annotations, the description carries the full burden and does so well: it discloses write authorization requirements, refusal in read-only sessions, blocking up to 120s, failure results returned as status fields rather than errors, and timeout behavior with the run continuing. This goes far 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 purpose is front-loaded, the write-access caveat is placed early, and the Args section is tightly scoped. Every sentence adds information; no 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 there are no annotations and no schema-level descriptions, the text covers the essential operational context: authorization, side effect, parameter behavior, and the non-exception failure modes. The output schema exists, so return-value details need not be restated.

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

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

Schema description coverage is 0%, so the description must compensate. It explains transformation_id as the transformation to run and gives rich semantics for wait: blocking up to 120s, failure/timeout result shapes, and instruction to check status rather than assume success. This is exactly the missing meaning.

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 'Trigger a transformation run,' a specific verb and resource, and the args clarify it acts on a transformation_id. It doesn't explicitly contrast with sibling trigger tools like trigger_pipeline, but the resource is unambiguous.

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

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

It states a clear precondition: it is a write tool available only with write access, and read-only sessions refuse it. It doesn't name alternatives or say when to prefer this over trigger_pipeline/compile_transformation, but the context is explicit enough.

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

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

With no annotations provided, the description carries the full transparency burden and succeeds. It discloses that this is a write operation, explains the authorization requirement, and details failure and timeout return shapes, including the critical warning to check 'status' rather than assuming a returned result means success.

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 organized with a front-loaded purpose, a clear write-access note, and an Args section. Every sentence adds operational value—access restrictions, wait semantics, failure representation, and timeout behavior—with no filler or repetition.

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 is fully sufficient for an agent to invoke the tool correctly: it covers required and optional arguments, permission prerequisites, result semantics, and edge cases like failure and timeout. Even though an output schema exists, the description still provides the key behavioral information needed, making it contextually 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 description coverage is 0%, so the description must fully compensate for the bare input schema. It explains upload_id as 'the upload to run' and gives rich semantics for wait: blocking behavior, 120s cap, failure/timeout result formats, and the caution not to assume success. Both parameters are meaningfully described.

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 'Trigger an upload run,' a specific verb and resource that clearly identifies the tool's function. This distinguishes it from sibling tools like trigger_pipeline and trigger_transformation by naming uploads as the target, so an agent can select it correctly without inspecting other schemas.

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 access context: it is a write tool that requires write permission, and read-only sessions refuse it. However, it does not explicitly discuss when to use this tool versus sibling trigger tools, leaving that differentiation mostly to the name and first sentence.

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