list_artifact_pipelines

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'bounded' and 'immutable' context, which suggests a stable, paginated listing and is consistent with a read-only operation. It does not, however, explain cursor/limit behavior or response characteristics beyond what annotations imply.

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?

One short, front-loaded sentence conveys the action, resource, and key filter dimensions with no filler. Every word contributes to the agent's understanding of what the tool does.

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 strong read-only/idempotent annotations and an output schema available, the description is mostly sufficient for a simple optional-filter listing tool. Explicitly mentioning pagination or pointing to get_artifact_pipeline for single-pipeline retrieval would make it more complete, but those gaps are minor given the schema and 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. It adds meaning for four of the six parameters by mapping to run, name, producer, and artifact (run_id, pipeline_name, producer, source_artifact_id). It omits limit and cursor, though 'bounded' hints at pagination; this is partial but not full compensation for the missing schema 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 uses a specific verb ('Discover'), a clear resource ('artifact pipelines'), and lists the main filter dimensions: run, name, producer, and artifact. This distinguishes it from siblings like get_artifact_pipeline or register_artifact_pipeline, though it does not explicitly name those alternatives. The phrase 'bounded immutable' adds a little ambiguity but does not obscure the core 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?

The description implies this tool is for finding pipelines matching run/name/producer/artifact filters, but it never states when to use this tool versus get_artifact_pipeline or compare_artifact_pipelines. No alternatives or exclusions are mentioned, so guidance is only implicit rather than explicit.

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