generate_pipeline_sql

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

No annotations are provided, so the description carries the full burden. It discloses branching behavior on outcome, the verbatim printing rule, the side effect of saving SQL when save_to_version_id is provided, the requirement to surface target_is_also_a_source conflicts, and the explicit prohibition on validating or summarising SQL. This is exceptionally transparent.

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?

Although long, the description is tightly organised with bullet points for outcome branches, bolded key directives, and front-loaded purpose. Every sentence conveys a necessary protocol detail, and there is no redundant content.

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, no annotations, and 0% schema description coverage, making this description the sole source of guidance. It covers all three outcome branches, the additional safety check for target_is_also_a_source, the UI selection workflow, and the save behavior. It fully prepares the agent to execute the correct workflow, making it complete for the tool's complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains `instruction` (must be verbatim, no added hints) and `save_to_version_id` (pipeline version to save SQL). It also clarifies `session_id` usage across calls and for approve_table_selection. `pipeline_id` and `knowledge_cluster_id` are not explicitly defined but are inferable from context and the phrase 'knowledge cluster's own instructions.'

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 'Ask the Data Engineering agent to write pipeline SQL,' a clear verb+resource statement. It distinguishes from siblings like get_pipeline_sql and save_pipeline_sql by indicating this tool generates SQL through the agent, not retrieves or saves it.

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 extensive procedural guidance: when to pass save_to_version_id, how to handle each outcome, and when to call approve_table_selection. It also includes explicit 'do not' instructions (e.g., do not validate generated SQL, do not renumber the review prompt). However, it does not directly name alternative tools for comparison, so the 'vs alternatives' aspect is less explicit.

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