Create Potential Change Order Line Item

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

Annotations already indicate non-read-only and non-destructive. The description adds one behavioral insight (automatic budget line item creation for non-budgeted line items) and mentions HTTP 201, but misstates the core action (creating a change order vs line item). This contradiction undermines transparency.

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 moderately sized and front-loaded with the action, but includes unnecessary/redundant phrases like 'Creates a new Change Orders' and API endpoint details. The note is valuable, but inaccuracies could be excised to improve conciseness.

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?

Provides basic context: HTTP 201 return, required parameters, and a notable side effect. However, lacks description of the line_item object structure, error cases, and differentiation from sibling tools. Output schema is absent, and the description does not compensate sufficiently.

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% with parameter descriptions, so baseline is 3. The description repeats the required parameters but adds no new meaning beyond the schema, except the budget line item note loosely related to the line_item parameter. No structural constraints are conveyed.

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?

Starts with correct verb 'Create' and resource 'Potential Change Order Line Item', but later misstates the action as creating 'Change Orders' rather than line items. The note about automatic budget line item creation adds clarity, but the inconsistency reduces overall purpose clarity.

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?

No explicit guidance on when to use this tool vs alternatives like create_potential_change_order or other line item creators. The description says 'Use this to create a new Change Orders' which is inaccurate and does not help differentiate.

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