ksef_start_invoice_draft

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

Annotations are all false, so they do not convey behavioral traits (e.g., readOnlyHint=false implies mutation but not destructive; idempotentHint=false suggests need for caution). The description merely says 'Create' without detailing side effects, authorization needs, rate limits, or data persistence behavior. With no annotation support, the description fails to adequately disclose behavioral characteristics.

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, no-filler sentence that immediately conveys the tool's function and output. It is concise and front-loaded. However, it could slightly improve with minimal structural optimization (e.g., separating main action from output with a period, not a comma).

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 the two parameters with no schema descriptions, the description is minimally complete: it states creation and a checklist return. But it does not clarify whether the draft is persisted locally, requires an active session, or how the seed object influences the draft. The existence of an output schema is known from context signals, but the description doesn't leverage that to reduce the burden. Still, it provides a basic functional outline.

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 adds no explanation for the two parameters ('seed', 'source_document_ids'). The parameter names are vaguely self-documenting at best, leaving the AI agent without guidance on their format, purpose, or relationship to the missing-field checklist. This is a critical gap.

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 explicitly states the core action ('Create an invoice draft') and the unique output ('return the missing-field checklist'), distinguishing it from other invoice tools in the sibling list like ksef_prepare_invoice, ksef_update_invoice_draft, or ksef_submit_invoice. The verb 'Create' clearly indicates a new draft being initiated.

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 (e.g., whether to start a fresh draft or use update_invoice_draft). It does not mention prerequisites (e.g., required session or authorization), nor does it exclude scenarios where other tools would be more appropriate. Without such context, an AI agent may misuse the tool.

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