Get exact workflow job logs

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

The description is fully transparent: it declares read-only behavior, idempotency (implied by 'read-only' and confirmed by annotations), non-destructive nature, and the fact that it never downloads an archive. It also mentions fingerprinting (sha256) and verification steps, giving insight into internal operations. This aligns perfectly with the annotations (readOnly, idempotent, non-destructive).

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 yet information-dense, covering purpose, constraints, supported options, and exclusions in a compact paragraph. Each sentence adds value (e.g., 'never downloads a workflow-run log archive' clarifies side effects, 'sha256 fingerprints' adds transparency). No superfluous words or redundant details.

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 extensive sibling tools list, this description clearly distinguishes gh_get_job_logs from related tools like gh_get_run_logs or gh_get_failed_run_logs by emphasizing exact job and attempt, read-only streaming, and no archive download. The presence of an output schema and the tool's focused scope make the description complete for selecting this tool appropriately.

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?

All 8 parameters have detailed descriptions in the schema (100% coverage), and the tool description adds semantic context for key parameters: start_marker is explicitly 'never treated as a regex', tail_bytes returns 'final bounded UTF-8 bytes', max_bytes is 'capped by server policy', and attempt is 'exact'. This enriches the schema and clarifies parameter usage.

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 is extremely specific: it clearly states this tool retrieves logs for a single exact GitHub Actions job and explicit attempt, is read-only, and supports bounded streaming with options like byte caps and markers. It also lists what operations it does not expose (regex, shell, rerun, cancel, delete, dispatch), leaving no ambiguity about its 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 provides explicit usage guidance: it is read-only, streams bounded plaintext logs, never downloads a workflow-run archive, and verifies attempt membership before and after retrieval. It also clarifies that start/end markers are literal, not regex, and that max_bytes is capped by server policy, which helps the agent use it correctly.

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