Github Get Job Log

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

Annotations already cover the safety profile (readOnly, non-destructive), and the description adds genuinely useful behavioral context: the tail-preserving cap and the one-minute redirect to a storage host where the download proceeds without the token. That auth nuance is not derivable from annotations or schema.

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?

Three sentences, front-loaded with purpose and cap behavior; each earns its place except the cryptic 'See #500' reference which adds little for an agent without issue context.

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?

An output schema exists, so return values need not be described, and annotations carry the safety profile. The description covers the cap/tail behavior and the redirect/auth nuance, leaving only the undocumented repo_owner/repo_name fields as a minor gap.

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 coverage is 50%: job_id and max_bytes are documented in the schema, and the description restates the max_bytes tail-cap behavior rather than adding new meaning. repo_owner and repo_name are undocumented in both schema and description, so compensation is incomplete.

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?

States a specific verb (fetches) and resource (GitHub Actions job's log) with a clear scope constraint (capped at max_bytes, keeps the tail). It is easily distinguishable from siblings like github_rerun_job or github_get_pr_status_checks.

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?

Usage is only implied via the rationale that 'a job reports its failure last, so a cut keeps the tail', which hints at failure debugging. The schema ties job_id to github_get_pr_status_checks and the description points to github_get_skill('pr-analysis'), but there is no explicit when/when-not guidance or named alternative for fetching logs.

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