task_escalate

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

With no annotations, the description carries the full burden and delivers substantial behavioral disclosure: the state transition semantics (`escalating` blocks running and is non-terminal), the persistence of question + options, the auth gate (current attempt_id required; handoff/forged tokens rejected, preventing stale submissions), and the lifecycle (monitoring aggregates reports with raised_at age; resolution via task_decide returns the task to running). This far exceeds schema-level information.

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?

Purpose is front-loaded ('决策上浮 worker 遇方案选择/疑问…') and the paragraph is information-dense with no filler. It is one long run-on sequence that packs state semantics, auth rules, and lifecycle into a single flow, which is efficient but could benefit from light structuring. Every clause 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?

For a stateful human-in-the-loop tool with no annotations and no output schema, the description covers the state transition, blocking behavior, auth requirement, non-terminal nature, monitoring, and resolution path via task_decide. Missing are the return value on success/failure and edge cases such as re-escalating an already-escalating task — minor gaps for a tool of this 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 75% — question, options, and attempt_id are already documented in the schema. The description adds context about how these params are used (persisted for the human decision) and the '防迟到' rationale for attempt_id, but task_id remains undocumented in both, and the added param-level meaning is marginal beyond the schema. Baseline 3 is appropriate.

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 trigger and action: escalate a decision upward when a worker faces方案选择/疑问, transitioning the task to `escalating` state and storing question + options. It names the exact resource (task) and effect (running blocked, waiting for human decision), and differentiates itself from the sibling task_decide by describing the complementary resolve-downward flow.

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 usage context is explicit: use when a worker encounters a choice/uncertainty requiring human judgment. It also sketches the workflow — user answers, then task_decide issues the decision, then the task returns to running — which tells the agent how this tool fits alongside siblings. It stops short of explicitly stating when not to use it versus alternatives like task_fail or task_approve, so a 4 rather than a 5.

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