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

With no annotations, the description must carry the full burden. It discloses the update semantics and a key constraint ('传入的更新字段不能为空' - update fields cannot be empty), but does not mention permission requirements, error behavior, or whether unspecified fields are preserved. This is adequate but with notable gaps.

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 description is two short sentences that front-load the primary purpose and immediately follow with the update-by-id mechanism and constraint. There is no redundant information, making it optimally concise.

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?

Given the simple update operation, full parameter coverage in the schema, and absence of an output schema, the description suffices for an agent to understand the tool's core behavior. It could mention that existing fields not passed are preserved, but the '按...更新字段' phrasing implies partial update, so it is nearly complete.

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?

The input schema covers all 9 parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by clarifying that the update fields must not be empty, a constraint not evident from the schema. This extra semantic detail justifies a 4.

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 clearly states the tool modifies project experience by ID and updates specific fields. The verb '修改' (modify) and resource '项目经历' (project experience) are explicit, distinguishing it from sibling tools like add-project-exp or modify-work-exp.

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 description implies usage for updating existing project experience records, but it does not explicitly say when to use this instead of add-project-exp or other modify tools. No exclusions or alternative tool references are provided, making the guidance implied rather than explicit.

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