Show Potential Change Order Line Item

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

Annotations already declare readOnlyHint=true. The description adds valuable context: 'Change Event Line Item information is only returned if a line item is associated to a change event line item and user can view change events.' This conditional behavior is not in annotations, improving 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?

Each sentence adds value: main action, conditional behavior, usage instruction, return type, required params, API reference. The paragraph is compact but could be more structured (e.g., separate lines). No redundant sentences.

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?

The description covers the main purpose, required parameters, and conditional behavior, but lacks details on pagination (page/per_page) and the response structure beyond 'JSON object'. Since there is no output schema, more specifics about the returned fields would improve completeness.

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 schema already describes all parameters. The description merely lists required parameters again without adding extra meaning. It does not explain defaults for page/per_page or their impact. Baseline 3 is appropriate.

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 'Return a Potential Change Order Line Item' and explains the conditional return of change event line item info. However, it uses 'Change Orders' plurally in the usage statement, which may slightly confuse since the tool returns a single line item. Overall purpose is discernible.

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 says 'Use this to fetch the full details of a specific Change Orders by its identifier' and lists required parameters, providing clear context. However, it does not mention when not to use this tool vs alternatives like the list endpoint, nor does it refer to sibling tools for listing or updating.

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