freeagent_create_bill

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

Annotations indicate readOnly=false and destructive=false, so 'Record' is consistent. The description adds useful behavioral context about line requirements and the receipt-search workflow, but does not disclose other traits such as what state changes occur, required permissions, failure modes, or how results are returned. It neither contradicts annotations nor fully enriches them.

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 and front-loaded: the first sentence states purpose, and the second adds an actionable workflow note. Both sentences earn their place with no filler or repetition.

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 create operation with no input schema, no output schema, and minimal annotations, the description is too sparse to allow confident invocation. It fails to provide the required field structure, how to specify suppliers/contacts, handling of multiple line items, or response expectations. The mention of fileBase64/fileName suggests a richer parameter set that is not captured, leaving significant gaps.

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?

With an empty input schema, the description has no obligation to document parameters, but it still adds meaning by mentioning that each line needs a spending category and value including tax, and by referencing fileBase64 and fileName for the PDF. The reference to parameters not present in the schema introduces slight ambiguity, but given the 0-param schema, the description provides more than expected.

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 uses 'Record a supplier bill' with a clear verb and resource, and immediately clarifies that this is an invoice the company has received and owes, distinguishing it from other tools like create_invoice or create_expense. It also specifies the core line-item requirements, reinforcing purpose.

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 gives clear context for when to use the tool (recording supplier bills) and includes a specific recommendation to search connected email tools before asking for a PDF. However, it does not explicitly compare with alternatives or state when not to use it, so it stops short of a 5.

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