resume_job_observation

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

The description adds substantial behavior beyond the annotations: no re-upload/re-parse, idempotency semantics ('同一版本的恢复决定不会重复应用', consistent with idempotentHint=true), the 40306 re-stop rule, and a minimum 3-second query interval. It does not contradict any annotation (readOnlyHint=false fits a state-changing resume).

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 single dense paragraph front-loads the key condition (only resume on explicit user request) and each subsequent clause carries distinct information, with no filler. It is somewhat run-on and would benefit from sentence breaks, but every statement earns its place.

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?

An output schema exists, so return values need not be explained. Given the complex rate-limit/idempotency semantics involved, the description covers the necessary behavioral context well; the main gap is that the four required parameters (0% documented) receive only partial explanation.

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 carry the full burden. It compensates partially: it explains that expected_attempt and expected_observation_revision come from get_job and that missing values default to 1 and 0, and it constrains user_note's meaning. However, it does not describe format or usage of job_id and only loosely characterizes user_note's required content.

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 states a specific verb+resource: resume querying the original job observation after rate-limit 40306 handling, and explicitly scopes out re-uploading/re-parsing. An agent can distinguish it from generic parse/get_job siblings, though the opening precondition ('限流40306处理后') makes the core purpose slightly context-dependent rather than front-loaded.

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 an explicit trigger ('仅在用户明确要求时恢复') and a stop condition ('再次40306仍停止'), plus a prerequisite step (先 get_job 取得 attempt_number 和 observation_revision). It lacks explicit naming of alternative tools to prefer, but the when-to-use and when-to-stop guidance is clear.

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