job_log

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

Adds real context beyond readOnlyHint/openWorldHint: output is normalized (no timestamps/colors), tail is capped at 500, and log content is explicitly framed as untrusted data with an instruction not to follow anything inside it. That injection warning is valuable safety context for an open-world read. It stops short of saying what happens when tail exceeds 500 or whether truncation is signaled.

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 tight sentences, each doing distinct work: what the output is, how the two optional params modify it, and how to treat the content. The safety note is placed last, after the functional facts are already front-loaded.

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 shape needn't be described, and the description covers normalization, filtering, and trust boundaries. Minor gaps remain: whether truncation is visible in the result and what errors occur for an unknown job_id or over-limit tail.

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 0% — properties carry only titles — so the description carries the load, and it does well for the two non-obvious params: pattern is a Python regex that keeps matching lines, tail keeps the last N with a 500 ceiling. repo and job_id are left entirely undefined, though their meaning is largely self-evident from context.

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?

Names the resource precisely ('lines from one job's log') and the transformation applied (timestamps and color codes removed), which distinguishes it from get_run and failure_summary. It never states the operation as a verb (fetch/read) and leaves the repo/job_id scoping implicit, but the identity is unambiguous.

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?

Explains how the optional modifiers behave (pattern filters, tail truncates to the last N) but never says when to choose this tool over get_run or failure_summary. An agent must infer that this is the raw-log view while siblings offer structured summaries.

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