myob_bill_prepare_create

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

With no annotations, the description carries full responsibility for disclosing side effects. It only says 'Requires approval before commit,' which hints that the action is non-final, but it does not clarify what 'prepare' does (e.g., validation, draft creation), what data it consumes, or any effects on the system.

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 one short sentence with no redundant words. It picks up the essential purpose and a key constraint, making it highly efficient.

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?

The tool operates in a complex prepare/commit/approval ecosystem with siblings like myob_commit_operation and myob_approval_*. The description omits the overall workflow, how to proceed after preparation, and the structure of json_body. Despite having an output schema, the description leaves too much to be inferred for a non-trivial operation.

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 0%, and the description never mentions json_body, layout, or business_id. It fails to provide any guidance on what fields are needed for a purchase bill, what layouts are valid, or how to specify the business context.

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 a specific verb+resource: 'Prepare creation of a purchase bill.' It clearly distinguishes this from sibling tools like myob_bill_prepare_update (update) and myob_bill_list/get (read), and from generic prepare tools like myob_entity_prepare_create.

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 phrase 'Requires approval before commit' implies a two-phase workflow and signals that this is not the final commit step. However, it does not explicitly state when to prefer this tool over alternatives or mention any exclusions, such as using myob_bill_prepare_update for existing bills.

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