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

With no annotations, the description carries the full burden, and it does disclose real behavior: which events are traced, that every transaction gets a /v1/proof/tx verify link, and that prove:true changes behavior by proving each state live under the superroot. It still omits safety posture (read-only?), cost/latency implications of prove:true, and any auth requirement, so it is helpful but incomplete.

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 purpose is front-loaded and the two sentences are not padded, but the second half is a dense run of domain jargon (observatory's decode, the layer's records, whitepaper's closed-lifecycle table) that costs parseability without adding routing signal. Not wasteful, but not clean.

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?

There is no output schema and no annotations, so the description must carry both; it does describe the return surface (state table, events, proof links), which partially substitutes for an output schema. For a 4-parameter tool it still leaves job_id/chain_id semantics and any safety or cost guidance unstated.

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 only 25% — only tenant is documented in the schema. The description does add real meaning to prove ("prove:true proves each live under the superroot"), which the bare boolean schema does not convey. However, job_id (the required parameter) and chain_id receive no explanation in either place, leaving half-plus of the semantics undocumented.

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 opening clause names a specific resource and scope — the complete lifecycle of a job, traced and verifiable — which is more than a restatement of the name. It enumerates what is folded in (hook state, on-chain events, observatory decode, layer records, lifecycle table), so an agent knows this is a consolidated trace. It never names or contrasts a sibling such as taifoon_hire_path or taifoon_hiring_stages, so 5 is not warranted.

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?

There is no statement of when to call this versus the many sibling lifecycle tools (taifoon_hiring_stages, taifoon_hire_path, taifoon_hire_assemble). No prerequisites, no when-not-to-use, no named alternative. Usage must be inferred purely from the resource description.

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