freeagent_create_invoice

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

Annotations only provide readOnlyHint=false, idempotentHint=false, destructiveHint=false, which give minimal context. The description adds critical behavioral information: the invoice is created as a DRAFT and is not sent to the client. This is a key side effect not inferable from annotations or schema. It could go further by noting response shape, but the draft disclosure is substantial.

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 short paragraphs: the first states the tool's purpose and key behavioral note, the second gives the lookup workflow. Every sentence contributes useful information; no redundancy or filler.

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?

Given 10 parameters and no output schema, the description covers the essential workflow (draft creation, next step to send, prerequisite lookups). The schema handles parameter details. A more complete description might mention the response format or error handling, but for a create operation with a rich schema, this is adequate.

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?

The schema already provides 100% coverage for all 10 parameters, so the baseline is 3. The description adds practical guidance for two key parameters (contact and categoryUrl) by telling users to look them up with dedicated list tools and giving an example category URL ('001 Sales'). This goes beyond the schema's formal descriptions.

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 opens with 'Raise an invoice in FreeAgent' — a specific verb with a clear resource. It immediately distinguishes itself from sibling tools like freeagent_update_invoice_status and freeagent_delete_invoice by clarifying it creates a draft, not a sent invoice.

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?

Explicitly states when to use this tool (raise a draft invoice) and directs users to freeagent_update_invoice_status for marking as sent. Also provides lookup guidance for contacts and income categories via freeagent_list_contacts and freeagent_list_categories, naming the exact sibling tools.

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