post-crm-v3-objects-objtype-batch-update_update

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

With no annotations, the description carries the behavioral burden. It adds the requirement for a body parameter and shows a concrete example of the input shape, plus the ability to update by internal ID or unique property values. However, it does not disclose partial-failure behavior, whether the batch is atomic, response format, or permission requirements—important 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 compact: two sentences and one inline JSON example. It front-loads the primary action and then provides a concrete usage example. Every sentence earns its place, and the example is directly useful for invocation.

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 batch mutation tool with no annotations and no output schema, the description is minimally adequate: it identifies the operation, required body, and example. But it omits the required objectType path parameter (only visible in schema), ignores failure/partial-success semantics, and does not explain the response. It also lacks any guidance on choosing between v3/v4 or object-type-specific batch update siblings.

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 the baseline is 3. The description adds value by explaining updatable objects can be identified by 'internal ID, or unique property values,' which maps to the id/idProperty fields in the schema. The example illustrates how to structure the inputs array with id and properties, going slightly 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?

The description clearly states the action: 'Update a batch of objects by internal ID, or unique property values.' It specifies the resource (batch of objects) and the two addressing modes, which helps distinguish from single-object update or batch create/read/archive siblings. However, it does not explicitly differentiate from the many similar batch-update endpoints for specific object types (e.g., quotes, invoices) or the v4 variant.

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 implies usage for batch updates and explicitly says 'REQUIRES body parameter with objects to update,' giving a task-level requirement. But it does not state when to prefer this tool over alternatives like single-object PATCH, batch upsert, or batch create, nor does it mention exclusions such as when idProperty is required.

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