flow_log_tail

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

With no annotations provided, the description carries the full burden, and it does well: it discloses that grep is a case-insensitive regex, filters the WHOLE log first, and returns the last matching lines with line numbers. This is meaningful behavioral information beyond the tool name. It does not discuss errors or permissions, but the read-only nature is reasonably implied by 'Return the tail.'

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 compact and front-loaded, with the core purpose stated first and a useful example following. Every sentence earns its place; there is no filler or repetition of schema information.

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?

For a read-only log-tail tool with an output schema, the description covers the purpose, log scope, grep behavior, and line-number output. The main gap is the lack of any guidance about when to use this tool versus sibling log/status tools, but the core calling semantics are sufficiently complete.

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 compensate. It explains the non-obvious grep parameter in detail with a concrete example, and the phrase 'last lines matching lines' conveys the role of the lines parameter. job_id is self-explanatory from the tool name and the required field. Some explicit lines-parameter documentation would be nice, but the description adds real semantics where the schema is silent.

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 opens with a specific verb and resource: 'Return the tail of a Flow job's combined stdout/stderr log.' This clearly identifies what the tool does and the 'combined stdout/stderr' detail distinguishes it from status or summary-oriented sibling tools.

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 usage for retrieving filtered tail output from a Flow job log and gives a concrete grep example, but it never explicitly states when to prefer this tool over alternatives like flow_status or flow_jobs. There are no exclusions or alternative routing clues beyond the tool name itself.

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