Updates a watsonx project's name or description with a partial flat JSON PATCH request, so you can change project details without replacing the full resource.
PATCH with a flat, partial JSON object — confirmed live. NOTE: this PATCH body format is specific to projects; update_job needs a JSON Patch array instead (see spec/03-conventions.md).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| project_id | Yes | ||
| description | No |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply idempotentHint=true, so behavioral disclosure largely rests on the description, and the phrase 'flat, partial JSON object' usefully implies unspecified fields are left untouched. However, it omits permission requirements, whether a null value clears a field, and what the response contains — meaningful gaps for a mutation tool.
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?
It is short and free of padding, but the lead sentence is spent on transport format rather than what the tool does, and the pointer to 'spec/03-conventions.md' is an external reference an agent cannot resolve at call time. 'Confirmed live' is assertion without operational value.
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 mutating tool with three parameters, no output schema, 0% schema coverage and only idempotentHint in annotations, the definition should say what gets updated, what happens on null, and what comes back. Instead it covers only body-format convention, leaving the core semantics to inference.
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 compensate, and 'flat, partial' does convey that all fields sit at the top level and that omitted fields are not modified. It still says nothing about the null-default semantics of name and description (does passing null clear the value?) or the role of project_id as the sole required identifier.
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 never states that this tool updates a project's attributes; it opens with 'PATCH with a flat, partial JSON object', which describes wire format rather than purpose. An agent can infer 'partial update' from 'PATCH' and 'partial', but the resource and effect are only guessable from the tool name, not the text.
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?
There is no explicit when-to-use guidance, and no comparison to siblings like update_connection or update_project_member. The one sibling reference, update_job, is about body-format mechanics ('needs a JSON Patch array instead'), which is correctness info rather than a rule for choosing between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.