supervise_agent_job

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

With no annotations, the description carries the full burden, and it discloses meaningful non-obvious traits: supervision is local, non-LLM, runs on a 300-second interval, targets one known job, and does not itself schedule or wake GPT. It also states that native dispatches auto-enable it. It omits some mutation details (persistence of enabled state, what happens on a detected stall, reversibility).

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?

Four short sentences, front-loaded with the core action, followed by scope constraints, auto-enable note, and the acknowledge caveat. Every sentence carries distinct information with no redundancy.

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 mutation tool with no annotations, no output schema, and three params, the description covers purpose, side-effect boundaries, automatic enablement, and the acknowledge caveat. It could say more about state persistence or required job preconditions, but it is adequate for correct invocation.

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 supply meaning, and it touches all three parameters: 'one known job' scopes job_id, 'enable/disable' explains enabled, and 'Acknowledge a stall only after reviewing it' explains acknowledge. The acknowledge semantics remain somewhat shallow (what acknowledging actually does mechanically), keeping it out of 5 territory.

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+resource (enable/disable supervision of a job) and clarifies what it is not (does not schedule or wake GPT), which distinguishes it from dispatch/wake tools. It stops short of naming a sibling like check_agent_job or get_agent_job_status to complete the differentiation, so it's clear but not fully routed.

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?

Provides implied usage guidance: 'Native dispatches enable it automatically' hints when manual invocation may be unnecessary, and 'Acknowledge a stall only after reviewing it' constrains the acknowledge action. However, there is no explicit when-to-use vs alternatives versus check_agent_job or get_agent_job_status, leaving selection partly to inference.

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