create_bill

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Create,' which implies a mutating operation, but it does not explain side effects, whether the bill starts open, validation behavior, or what a successful creation returns. The description adds minimal behavioral context beyond the operation name.

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 a single compact sentence with no filler, front-loading the action and resource. It is appropriately concise, though it is so terse that it may under-specify for a tool with 17 parameters, so it does not earn a perfect structure score.

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 17-parameter creation tool with no output schema and no annotations, this one-liner is incomplete. It omits prerequisites, how the created bill behaves, how required versus optional fields are determined, and what the caller should expect after creation. It provides only the most basic domain context.

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 description coverage is only 12%, and the description names none of the 17 parameters. Required fields such as billDate, vendorId, and entries are left entirely to the schema, with no explanation of how they relate to creating a valid vendor bill. Given the low schema coverage, the description needed to compensate but does not.

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 a specific verb and resource: 'Create a vendor bill in Bigcapital.' It is distinguishable from sibling tools like update_bill, open_bill, and list_bills by the word 'Create,' and the phrase 'vendor bill' separates it from customer-facing creation tools like create_invoice. However, it does not explicitly differentiate itself from related creation tools or explain the vendor-bill concept, so it stops short of a top score.

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 no guidance on when to use this tool versus alternatives such as update_bill, open_bill, list_bills, or create_invoice. It does not mention prerequisites like an existing vendor, when a bill should be created instead of an expense, or any conditions that would select this tool over its siblings.

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