proforma_invoices_accept

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

No annotations are provided, so the description carries full behavioral disclosure burden. It states the status transition and readiness for conversion, which is useful, but doesn't disclose reversibility (can an accepted proforma be un-accepted?), required permissions, or whether the proforma must be in a particular prior state (e.g., sent) for acceptance to be valid. For a state-transition mutation with zero annotation coverage, this is a meaningful gap.

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 concise sentences, zero waste. Each sentence earns its place: the first states the action, the second states the consequence. Could arguably mention reversibility or prerequisites, but for a simple mutation tool this is appropriately tight.

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 2-param mutation tool with a fully documented schema and no output schema, the description covers the core purpose and the downstream consequence. However, without annotations, it omits important behavioral context like whether acceptance is reversible, what happens if the proforma is already in a cancelled/rejected state, and whether any validation occurs. This creates gaps a careful agent would want clarified.

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 documents both parameters (uuid and companyId). The description adds no parameter-specific detail beyond what the schema already provides. Baseline 3 is appropriate since the schema does the heavy lifting and description doesn't contradict or add conflict.

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+resource ('Mark a proforma invoice as accepted') and specifies the resulting status transition ('Transitions status to accepted'). It distinguishes itself from sibling tools like proforma_invoices_reject, proforma_invoices_cancel, and proforma_invoices_convert by describing the accept workflow step. It doesn't explicitly distinguish from siblings, but the action is specific enough.

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 sets clear context that this is the acceptance step and that after acceptance 'the proforma is ready to be converted to a final invoice', which implies the ordering relative to proforma_invoices_convert. However, it doesn't explicitly mention when NOT to use it or name alternative tools like reject/cancel, though the implicit workflow ordering provides decent guidance.

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