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

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description goes well beyond: it discloses that the message reaches a third party (the buyer), that sender address/template come from account settings or defaults, the KSeF side effect, the per-call confirmation behavior, and the required API key scope.

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?

Front-loads purpose and attachment behavior, then prerequisites and side effects. Mostly earns its length, though the confirmation guidance is stated twice ('you confirm each call' and 'confirm with the user before each call'), a minor redundancy.

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 send-with-side-effects tool with no output schema, it covers the recipient resolution, account-level prerequisites, KSeF implications, confirmation posture, and auth requirements. Nothing essential to correct invocation is missing.

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 coverage is 100% and the schema already documents recipient_email's default and invoice_id's source. The description's routing sentence ('buyer's address stored in the contractor record, or recipient_email if you give one') largely restates that, so it adds little beyond the schema; baseline 3 applies.

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?

States a specific verb (email) and resource (an issued invoice), adds the attachment detail, and distinguishes itself from siblings like ifirma_send_invoice_to_ksef and ifirma_send_payment_reminder. An agent can identify the action without opening the schema.

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?

Gives an explicit sequencing rule ('send to KSeF first' if no offline QR codes) that routes the agent between this tool and a sibling, plus a confirmation policy. It covers both when to call and a precondition for a related alternative.

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