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

Annotations already flag destructiveHint and non-idempotency, but the description adds genuinely new behavior: the call does not commit until a human approves the exact request in Settings > MCP and execute_approved_action runs, and that org-level MCP approval policy is configurable while business workflow approvals always apply. That is material context an agent could not derive from the annotations. It still omits whether the edit is a partial merge or full replacement of unspecified fields.

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 core action is stated early, but the leading 'Use this when working with RetailHardHat change_requests records in the connected organization' sentence is boilerplate that conveys no actionable constraint. The approval caveat, arguably the most important sentence, sits in the middle rather than being front-loaded.

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?

An output schema exists, so return values need not be explained, and the async approval gate is documented well. However, for a destructive mutation over a nested 8-field financial payload with zero schema documentation, the definition leaves the field-level semantics entirely unaddressed, which is the largest remaining hole.

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%, so the description is responsible for explaining changeRequestId, changeRequestLineItemId, and especially the nested data object with unit, labor, quantity, materials, unitPrice, totalPrice, notes, and description. It says nothing about them, including the critical question of whether omitted fields are preserved or cleared — a serious gap for a 'financial' mutation.

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 and resource: 'Edit a financial change-request line item,' and the 'financial' qualifier narrows it against non-financial siblings like update_change_request. It never names the adjacent tools (update_change_request, create_change_request_line_item, delete_change_request_line_item, update_budget_line_item), so the agent must infer the boundary from the name alone.

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?

'Use this when working with RetailHardHat change_requests records in the connected organization' is a generic context opener rather than a selection rule; it never says when to edit a line item versus editing the parent change request or creating a new line. The approval-workflow paragraph clarifies the execution path but not tool selection among the many update_* siblings.

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