Update client

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

Annotations already mark this as a non-read-only, non-destructive, idempotent operation. The description adds the important behavioral trait that only provided fields are changed, preventing an agent from assuming a full replace. It does not cover error handling or side effects, but the annotation coverage lowers the bar and the partial-update statement is meaningful.

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 short sentences, front-loaded with the main action and followed by a crucial caveat. There is no repetition of schema details or unnecessary context, so every word earns its place.

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 the 11 parameters and no output schema, an agent still needs to know which identifier to use when both clientId and customClientId exist, and what the response indicates. The description covers the core update operation but leaves these operational details to inference, making it adequate but not comprehensive.

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 27%, with 8 of 11 parameters having no descriptions. The description does not explain individual field meanings, such as the difference between phone and mobile or the semantics of customClientId, and it fails to compensate for the low coverage. The partial-update concept is helpful but does not resolve field-level ambiguity.

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 uses a specific verb ('update') and resource ('existing client'), making the tool's purpose unambiguous. It also adds the partial-update qualifier 'Only fields provided are changed,' which differentiates it from create or replace operations among the sibling 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?

The description clearly implies this tool is for modifying an existing client, which is enough to distinguish it from icount_create_client or icount_delete_client. However, it does not explicitly state when not to use it or name any alternative tools, so it falls just short of full guidance.

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