Start a background log

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

With no annotations at all, the description carries the full behavioral burden and does well: it discloses that logging is asynchronous, that other tools keep working meanwhile, that a job id is returned, and that a job_stop call is required to end it. Gaps remain around file overwrite behavior, error handling, and whether the job survives until 'duration' elapses.

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?

Two sentences, front-loaded with the action and the column set, then the job lifecycle. Nothing is redundant and the 'other tools keep working meanwhile' clause earns its place by disclosing the non-blocking behavior.

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 four-parameter background job tool with no output schema and no annotations, the description covers the return value (job id), the follow-up workflow, and the non-blocking property. It is nearly complete, with only edge cases like overwrite semantics or default file collision left unspecified.

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 75%, so the schema already explains 'out', 'every', and 'duration'; the description mentions CSV/JSONL format but only restates what the enum in the schema shows. It adds no new meaning for the four parameters, so the baseline of 3 applies.

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: 'Log the status to a CSV (or JSONL) file in the background,' and even enumerates the recorded columns, so the agent knows exactly what the tool produces. It does not differentiate against non-job siblings such as 'watch' or 'status', which may overlap in monitoring intent.

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?

It gives a clear lifecycle: 'Returns a job id; follow with job_status, end with job_stop,' which tells the agent what to do before and after invoking the tool. It does not state when to prefer this over alternatives like 'watch' or a one-off 'status' read, so the when-not guidance is absent.

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