invoices_efactura_message

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

Goes well beyond the annotations: it discloses the delivery path (ANAF hands the message to the seller under the invoice's upload index), states the key side-effect boundary ('the invoice itself is not changed'), and adds an operational limit (max 4000 characters) plus the token prerequisite. Note a mild tension worth flagging: 'Send a message' is an outbound action while readOnlyHint=true, but the description's explicit 'invoice itself is not changed' reconciles this rather than contradicting it.

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?

Three tightly packed sentences: action and use cases first, delivery mechanics second, prerequisites and limit last. No filler, and the constraint (4000 chars) is placed where it is needed rather than buried.

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?

Covers prerequisites, mechanism, side effects and length limits for a no-output write operation, which is most of what an agent needs. It stops short of saying what, if anything, comes back (message ID, status) for a tool with no output schema, which would close the last gap.

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 100%, so uuid/message/companyId are already documented, and maxLength 4000 is in the schema too. The description adds little parameter-level detail, only implying that uuid must reference a received invoice with an upload index and that the company needs a valid token; 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 and resource ('Send a message to the issuer of a RECEIVED e-Factura through SPV') and enumerates the three concrete use cases: dispute, request correction, deny ownership. It clearly separates itself from the read-side siblings (efactura_messages_list/efactura_messages_get) by emphasizing RECEIVED and outbound delivery.

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?

Preconditions are explicit: 'Needs a received invoice with an ANAF upload index and a valid e-Factura token on the company.' It frames the tool around received (not issued) invoices, which implicitly excludes the invoices_issue/submit family, but it never names an alternative tool or an explicit when-not-to-use case.

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