progress

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

Annotations declare a non-read-only, non-idempotent, closed-world write. The description adds genuinely useful context beyond that: the update is not final, it doesn't wake the sender, and it surfaces to the sender through track/wait_reply. It stops short of clarifying rate/latency behavior but covers the key side-effect semantics.

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 behavioral guidance is front-loaded, the when-to-use line follows, and the two args are listed tersely with the one constraint that matters. No sentence is wasted.

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?

With an output schema present, return-value detail is unnecessary, and the description supplies purpose, timing, visibility, and both parameter meanings. Only the exact 'request id' source and any delivery latency are left implicit, which is minor for a 2-param progress ping.

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, and it does: id is 'request id' and note is 'where you stand, in one sentence (500 characters max),' supplying both meaning and a format constraint absent from the schema. The id mapping is thin, which keeps it from a 5.

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 frames a specific action: reporting interim progress on a request addressed to the agent, explicitly 'not final.' It distinguishes this from the final answer via reply, giving an agent enough to tell it apart from siblings like reply and track, though the generic tool name 'progress' does some of the work of obfuscation.

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 explicit timing ('at the start of a long task, then now and then') and an explicit exclusion ('the final answer always goes through reply'), plus the visibility relationship to track/wait_reply. That is when-to-use, when-not, and the alternative all in one place.

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