describe_pipeline

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

With no annotations provided, the description carries the burden. It discloses the tool's behavior by stating it returns a full manifest containing required inputs, tunable parameters, container image, and output file patterns. However, it does not explicitly state whether the operation is read-only or side-effect-free, though the verb 'return' and the context imply a safe query. The enumeration of output components adds transparency beyond a simple 'describe' statement.

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 at two sentences, with the primary function and contents in the first sentence and a usage tip in the second. Every word earns its place, and it is structured with the most important information upfront. No redundancy or unnecessary detail.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It specifies the exact components of the returned manifest, compensating for the lack of an output schema. It also provides contextual guidance on when to use it (before run_pipeline). There are no significant gaps given the tool's simplicity.

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 single parameter pipeline_id is fully described in the schema ('The pipeline id, as returned by list_pipelines'), providing high schema coverage. The tool description does not add parameter-specific details, but since schema coverage is complete, the baseline score of 3 is appropriate. The description adds contextual purpose but not additional semantic meaning for the parameter.

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: 'Return the full manifest for one pipeline' and enumerates the specific contents. It also distinguishes itself from run_pipeline by positioning itself as a pre-execution step. This makes the purpose unambiguous and distinct 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 explicit usage guidance: 'Call this before run_pipeline to learn exactly which inputs and params it expects.' This tells the agent exactly when to use this tool and why. The directive is clear and actionable, even if it doesn't explicitly mention when not to use it.

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