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

Goes well beyond the annotations by disclosing the key operational traits: per-record independent success/failure, that the reply enumerates outcomes, that matching is by name (consistent with idempotentHint=true), and the exact billing model ($0.01 per saved record, nothing if none found). It does not say what the failure reasons look like or whether partial retries are safe, which keeps it off a 5.

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 sentences, both dense with non-obvious information (batch cap, matching key, partial-failure semantics, pricing), with the scope and the sibling reference front-loaded. Nothing is restated from the title or schema.

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 with no output schema and rich annotations, this covers the things an agent actually needs: limit, identity key, isolation of failures, response shape summary, and cost. The remaining gap is that the per-record payload contract is only pointed at rather than summarized, and error causes are unspecified.

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 0% at the top level, so the description carries real weight here: it documents the 100-item cap and that entries are matched by name. It deliberately delegates the per-item field semantics to crm_save_company rather than re-documenting them, which is a useful pointer but leaves the agent dependent on another tool's definition for the nested shape.

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?

States a specific verb+resource ("Create or update up to 100 companies in one call") and pins the scope precisely with a hard limit. It explicitly distinguishes itself from the singular sibling by saying each item behaves "exactly like crm_save_company," so an agent can choose between the batch and single tool without opening either schema.

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 'up to 100 in one call' framing and the reference to crm_save_company make the intended use case (bulk upsert) clear, and 'matched by name' tells the agent how duplicates are handled. It stops short of an explicit 'use this instead of crm_save_company when you have more than one record' exclusion or guidance on batch size trade-offs, so it is strong context but not full when/when-not routing.

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