Pipeline Status

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

While annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, the description actually ADDS confusion rather than clarity. The mention of 'showing what's currently queued/running' in the description could be read as too narrow (suggesting only active items are shown) when active_only defaults to true but is configurable. No disclosure of rate limits, scope limitations, or details about 'live' semantics (is this a snapshot managed internally? What are the consistency guarantees during concurrent writes?). The description should clarify that this endpoint only reads and never mutates state, which is especially important when a sibling tool like autohold_create could be a follow-up action.

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?

Four short, active sentences. The 'live' framing and the explicit note about pollability are immediately useful. The mention of 'roughly 50%% smaller' is a useful approximation for agents considering retention versus bandwidth. Each sentence earns its place — no filler or redundant phrasing.

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 a 5-parameter tool defaulting active_only=true and zero schema coverage, the description must clarify query semantics, default behavior, and interaction between parameters, but doesn't explain why a user would set active_only=false. There's no mention of what the output contains (which the output schema presumably documents) but also no mention of time-window limitations, whether 'brief' affects the output schema differently, or whether pagination exists for large pipelines. The description covers the tool's nice-to-haves but leaves core behavioral gaps unfilled.

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 carries the full burden, but it doesn't do much beyond restating parameter names. The description says 'tenant' is 'default from env' and 'brief' 'reduces output' which mirrors the schema's own documentation, adding only marginal context about 'brief' reducing size by ~50% and tenant's env fallback. The main contribution is the '(default from env)' clarification for tenant — that's genuinely useful — but the context for pipeline and project is minimal, and there's no mention of query semantics for pipeline or project.

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 'Live pipeline status showing what's currently queued/running' uses a specific verb (get/show status) with a clear resource scope (pipelines) and states a behavioral trait (the 'live' aspect indicating real-time visibility into queued/running items). It's clear enough to distinguish from most siblings (e.g., get_build, list_jobs), though it doesn't explicitly name alternatives like list_pipelines. The Live/queued framing differentiates it from static resource-listing siblings like list_buildsets or get_config_errors.

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 polling usage via the 'brief' parameter ('for repeated polling') and is named 'Live pipeline status' with a default state of active_only=true, which implies it's for monitoring. However, there's no explicit when-to-use/when-not-to-use guidance, and with 43 siblings available (list_builds, get_build, diagnose_build, etc.), the description misses the opportunity to clarify when get_status is more appropriate than querying individual build status endpoints.

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