smokeball_create_bill

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

Annotations already signal readOnlyHint=false, destructiveHint=true, and idempotentHint=true, but the description adds useful behavioral context beyond them: routing through governed connector authority, the effect parameter being verified by Spring, idempotency_key as stable business-action identity, and approval_ref for resuming a write. This helps an agent understand the governed write-and-approval flow. However, it still does not disclose the actual business side effects of creating a bill in Smokeball.

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 compact and scannable, with a clean Args block that maps directly to the seven parameters. The initial sentence is redundant with the tool name, but the rest of the description is efficiently structured and avoids major padding.

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 tool that actually creates a bill in an external system, the description omits the essential domain payload: what should go into the `arguments` JSON string, what fields are required, and how the bill relates to Smokeball matters or trust accounts. With zero required parameters and all defaults, an agent still cannot determine what constitutes a valid create_bill invocation. The governance and idempotency details are helpful but do not make the definition complete.

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%, so the description carries the entire burden for parameter meaning. It does give at least a one-line explanation for all seven parameters, including useful context for effect, approval_ref, and idempotency_key. However, the most important parameter, `arguments`, is only described as "JSON string of arguments for the connector operation" with no indication of what fields a bill creation requires, and other labels like "Exact project correlation reference" add little real semantic value.

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 "Smokeball connector operation `create_bill` (platform tool `smokeball.create_bill`)", which is largely a tautology that restates the tool name. It never explicitly says "creates a bill in Smokeball", nor does it describe what a bill consists of or how this operation changes external state. The remaining sentence about governed connector authority is about routing, not about the tool's core 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 provides no when-to-use guidance, no alternatives, and no exclusions. It only says the operation "routes only through the exact project/account governed connector authority", which is a constraint, not a usage guideline. An agent cannot tell from the description when to choose `smokeball_create_bill` over other bill-creation tools or over `smokeball_api_request`.

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