Get Pipeline Step Logs

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

Annotations already mark the tool as readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond these by detailing the truncation behavior (only returning last max_bytes by default), the truncated flag in the response, the absolute byte window semantics of start/end, and the null behavior for total_bytes. This adds significant behavioral context not present in 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 well-structured with separate sections for Args and Returns, but it could be slightly more concise. The first paragraph clearly explains truncation and pagination, and each parameter gets a brief explanation. Minor redundancy exists (e.g., 'start/end are an absolute byte window' repeats the description in parameter docs), which trims the score from 5 to 4.

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 high complexity (8 parameters, 3 required), zero schema coverage, and presence of an output schema that likely documents return fields, the description covers all necessary aspects: parameter semantics, truncation/pagination behavior, UUID resolution guidance, and response fields. The output schema handles the return format, so the description need not repeat it. Complete for a complex log retrieval 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 description coverage is 0%, so the description must fully document all 8 parameters. It does so thoroughly: explains repo_slug, pipeline_uuid (with UUID vs build number distinction), step_uuid (from get_pipeline_steps), workspace (optional, defaults to configured), log_uuid (omit for main, pass service container UUID), start and end (absolute byte window, not 'last N'), and max_bytes (trailing slice default 100 KiB, pass null for whole log). No parameter is left undocumented.

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 explicitly states the tool retrieves logs for a specific pipeline step, using the verb 'Get' and the resource 'logs for a specific pipeline step'. It clearly distinguishes from sibling tools like get_pipeline_run or get_pipeline_steps by mentioning UUID resolution and step lookup. The resource and scope are precise.

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 guidance on when to use this tool (after resolving pipeline UUID and step UUID), and when not to (does not accept build numbers; recommends using get_pipeline_run for that). It also explains pagination behavior with start/end parameters and references sibling tools for UUID resolution, fulfilling the criteria for explicit when/when-not/alternatives.

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