stale_report

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

With no annotations, the description must carry the behavioral burden. It does state 'Read-only,' which is a useful safety signal, and it reveals that gpu.lock state is compared with lease claimants. However, it omits details like server-host file reads, permission requirements, output shape, and failure behavior; the schema's top-level note supplies some of this context.

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 one compact sentence plus 'Read-only,' with no filler. The four report categories are front-loaded, and every phrase contributes to the agent's understanding.

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 diagnostic with no required parameters, the description plus the schema's defaults and top-level explanation are mostly sufficient for a zero-argument call. It is not fully complete because there is no output schema and no guidance on how scope or staleness thresholds change the result, but the combination is adequate for this tool's complexity.

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 only 20%, and the tool description does not compensate by explaining scope, worker_stale_s, gpu_lock_dir, gpu_task_ids, or binding_token. The input schema carries the real parameter meaning, especially in its top-level description, so the tool description itself adds little value beyond hinting that gpu.lock and leases are involved.

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 the verb 'List' and names four concrete output categories: stale running workers, leases whose claimant is gone, a mismatched gpu.lock, and watchers of finished jobs. It also says 'Read-only,' which separates it from mutation-oriented sibling tools. The purpose is unmistakable and not a tautology of the tool name.

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 explains what the report contains but gives no guidance on when to choose stale_report over alternatives such as protocol_health or the worker/watch listing tools. There are no conditions, exclusions, or explicit use cases, so the agent must infer when this tool is the right choice.

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