Update estimate

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

The description goes beyond the annotations by disclosing two crucial behaviors: the items array fully replaces prior items, and only explicitly provided top-level fields are changed. This adds significant clarity about partial-update semantics and the destructive-ish replacement behavior for items, which annotations alone would not convey.

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 focused sentences deliver the essential information with no filler. The core purpose is front-loaded, followed immediately by the two behavioral rules that matter most for correct invocation: item replacement and partial top-level updates.

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 an update tool with 8 parameters and no output schema, the description covers the behavior that would otherwise be ambiguous: how items are handled and how partial updates work. It does not describe the return value or any special validation rules, but the required estimateId and optional fields are clear from the schema, so the description is sufficient for safe 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 description coverage is only 13%, so the description carries meaningful weight here. It explains the most complex parameter, items, by specifying replacement behavior, and it clarifies that omitted top-level fields remain unchanged. It does not document date/currency formats, but the parameter names are largely self-explanatory and the general update rule adds real semantic value.

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 tool updates an existing estimate, distinguishing it from creating, deleting, or sending estimates. It also adds the key semantic that items replace prior items, making the operational purpose unmistakable even among the many sibling estimate-related 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 gives clear context: use this for an existing estimate, and pass the full set of desired items for replacement. It does not explicitly name alternatives like create_estimate or delete_estimate, but the 'existing estimate' wording effectively implies the correct use case without confusion.

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