CGM profile update

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

With no annotations, the description carries the burden of disclosing behavior. It discloses the rejection of secret-containing fields and the requirement for explicit user intent, which is useful. However, it does not mention side effects, merge semantics, or error behavior, leaving some behavioral aspects unspecified.

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 sentences, front-loaded with the core action and resource, and includes the critical intent requirement and rejection rule. Every sentence earns its place, with no filler.

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 partial-patch tool with nested objects, the schema covers parameter structure, and the description covers intent and security constraints. It lacks explicit alternative guidance and merge behavior, but these are minor given the sibling set and the schema's clarity. Overall, it is sufficiently complete for correct invocation.

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 coverage is 100%, so both parameters are documented. The description adds value by specifying that the patch rejects fields with sensitive tokens (oauth/token/secret/etc.), which is a constraint beyond the schema's generic description. This meaningfully enhances parameter understanding.

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 action ('Persist a partial patch') and the resource ('shared Delx Wellness profile'). It distinguishes from siblings like cgm_profile_get by implying update vs read, and mentions the partial patch nature, making the purpose unambiguous.

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 provides a clear precondition (explicit_user_intent must be true) and a constraint (reject secret fields), but it does not explicitly compare to sibling tools like cgm_profile_get or state when not to use it. The usage context is implied but not fully spelled out.

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