Update a resource record

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

Annotations contain no safety flags (readOnlyHint=false, destructiveHint=false) and no concurrency hints. The description compensates fully: it discloses the merge semantics (only body fields change, untouched preserved), the write gating similarity to create_resource, the optimistic-concurrency behavior with conflict refusal, the dry_run behavior (runs gates, reports merged body without writing), and statement that unknown fields are dropped. This goes well beyond the annotations and is critical 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?

The description is three sentences, dense with information, and each sentence earns its place. Key operational guidance (merge vs full-replace, concurrency token) is front-loaded. No fluff, no repetition of schema. This is appropriately concise for a complex mutation tool.

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 5 parameters, no output schema, and rich semantics (merge, concurrency, dry_run), the description covers everything an agent needs: what the call does, how the merge works, how to avoid lost updates, what dry_run does, and the write gating. The sibling list helps the agent route to describe_resource for field details, which is referenced in the schema enum. No critical gaps are evident.

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 100%, so the schema already documents all 5 parameters. The description adds value beyond the schema by explaining the semantics of expected_updated_at (conflict refusal) and the merge behavior of body, which the schema only describes as 'Fields to change. Unknown fields are dropped.' The description clarifies the partial-update intent. This earns above baseline 3, but not 5 because the description doesn't add much about dry_run beyond the schema's 'Run every gate... without writing.'

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 verb ('Update'), a resource ('a record by id'), and critically distinguishes partial update from the portal PUT full-replace behavior. It also names a sibling (create_resource) for write gating. This clearly differentiates from update_block/update_config and the read tools.

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?

Explicitly instructs when to use the optimistic-concurrency token (expected_updated_at) for loop/parallel safety, mentions the same write gating as create_resource, and contrasts with portal PUT full-replace. It provides clear context and an exclusion (portal PUT does NOT do partial merge), which helps the agent choose this over alternatives.

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