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

The description discloses PATCH-like partial-update behavior, case-insensitive status/category handling, and the fact that closing is achieved by setting status rather than via a dedicated endpoint. Annotations only provide readOnlyHint=false and destructiveHint=false, so these behavioral details add meaningful context beyond the structured fields. It does not cover side effects like auto-populated date_closed or permission requirements, but it does not contradict the annotations.

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 three concise sentences, front-loaded with the core action and followed by high-value constraints. The parenthetical value lists are dense but efficient. Every sentence earns its place with no filler or repetition.

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 nine parameters and no descriptions in the schema, the description should clarify each field's role; it meaningfully covers status but also introduces a category field that is absent from the schema. Impact/probability scale semantics, date_closed format, responsible_owner meaning, and mitigation_actions are left unexplained. The closing guidance and partial-update behavior are valuable, but the schema mismatch and sparse parameter coverage make this only minimally 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?

With 0% schema description coverage, the description usefully supplies accepted values for status (Open|In Progress|Closed) and notes case-insensitivity. However, it references 'Category' as a parameter while the input schema has no category property and sets additionalProperties=false, creating a mismatch that could lead an agent to pass an invalid field. The partial-update note adds cross-parameter meaning, but most parameters such as impact, probability, date_closed, responsible_owner, and mitigation_actions receive no semantic explanation.

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 opens with 'Update a project risk,' a specific verb and resource that distinguishes it from projects_create_risk, projects_delete_risk, and projects_get_risks. It also clarifies that closing a risk happens through this endpoint, removing ambiguity about a separate close operation. This is a clear, resource-scoped definition.

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?

'Only the fields you pass are changed' tells the agent this is a partial update and that omitted fields are untouched. The statement 'Closing a risk is done here by setting status to Closed; there is no separate close tool' is an explicit when-to-use/when-not-to-use directive. It does not spell out when to use create or get instead, but the tool names and context make that largely self-evident.

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