Put Instances By Id

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered by structured data. However, the description adds nothing about what mutation actually occurs — critically, whether omitted fields in the body are cleared by this PUT, which is the single most dangerous unknown for a caller. No contradiction with annotations, but no compensating context either.

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 words are technically waste-free, but this is under-specification rather than conciseness — there is no front-loaded statement of effect, scope, or required inputs. The single sentence earns its place only as a placeholder.

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 a large nested body, conditional field dependencies (partner_tos_terms_accepted requires partner_tos_link and partner_tos_screenshot, dashboard users only), and no output schema, the description is completely inadequate. An agent cannot tell what the call returns, whether it is a full overwrite, or how the idempotency key interacts with the body.

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 only 33%: neither the `id` nor the `requestBody` wrapper is described, and the description supplies no meaning for them. The nested body fields do carry rich inline descriptions, which prevents this from being a 1, but the description itself contributes zero semantics beyond the schema.

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?

"Update Instance" merely restates the tool name and title (Put Instances By Id) without adding specificity. It does not distinguish this instance-settings update from near-identically named siblings such as PutV1InstancesCustomersById or PutV1InstancesMembersByUserId, so an agent must infer the resource target from the URL-shaped name alone.

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 guidance on when to use this tool versus alternatives, no prerequisites (e.g. dashboard-user-only fields, passkey/TOS coupling), and no note on whether it is a full replace or partial update. The sibling list contains many closer-scoped PUT/PATCH tools that the agent has no basis to choose between.

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