add_service_to_order

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action (add a service) but does not mention side effects such as whether the order is modified in place, whether it appends or replaces existing services, any permission requirements, or potential impacts on order totals. The mutation nature is implied but not elaborated, leaving significant gaps for a tool that alters an order.

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 concise, with two sentences that are front-loaded with the core purpose. The first sentence states the action, and the second explains the two usage patterns. There is no redundant or filler content, making it efficient for an agent to parse quickly.

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 tool without an output schema, the description adequately covers the essential invocation logic: the two modes and their associated parameters. It does not explain what happens after the call (e.g., whether the order totals are recalculated) or any prerequisites like order status, but these are not strictly required for a basic call. The absence of behavioral details lowers the score slightly, but the description is otherwise complete for selecting and calling the tool.

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?

While the schema covers 100% of parameter descriptions, the description adds semantic value by grouping parameters into two usage modes. It explains that fromCannedServiceId triggers a template copy including labor/parts/fees, whereas name/note/pricing creates a custom service. This goes beyond the raw schema and helps the agent understand the interplay between parameters.

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 verb 'Add' and the resource 'a service to a work order', with a specific and unambiguous purpose. It also distinguishes two modes of operation (canned template vs. custom), making it easy for an agent to understand what the tool accomplishes. It stands apart from sibling tools that operate on canned services rather than orders.

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 provides explicit guidance on when to use each parameter path: passing fromCannedServiceId for copying a template, or name/note/pricing for a custom service. This helps the agent decide how to invoke the tool. It does not explicitly contrast with alternative tools, but there is no direct sibling that adds a service to an order, so the guidance is sufficient.

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