update_work

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds that history is preserved, which is useful behavioral context, but it omits the concurrency/optimistic-locking semantics of expected_revision and what happens on a revision mismatch.

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?

Two compact clauses with the core mutation scoping front-loaded and the status enum appended. No filler, though the terse semicolon style trades clarity for brevity.

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 mutation tool with 5 required params, a nested metadata object, 0% schema coverage, and no output schema, the description is under-specified. It never explains the metadata shape or the expected_revision concurrency contract an agent must satisfy to call it correctly.

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 0%, so the description must carry the burden. It documents the selection enum (unread/reading/included/excluded/read) and the reason requirement for 'excluded', but leaves work_id, the free-form metadata object, and especially expected_revision unexplained.

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?

States a specific verb (修订/revise) and resource (题录和阅读/纳入状态), and the phrase '保留历史' distinguishes it from destructive siblings like delete_work. An agent can tell it edits an existing record rather than creating one, though it doesn't explicitly name any sibling.

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?

Gives one concrete usage rule ('excluded必须提供理由') but no guidance on when to prefer this over verify_work, add_work, or delete_work. Usage is implied rather than contrasted against alternatives.

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