wafeq_credit_notes_tax_authority_report_create

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

The description goes well beyond the annotations by stating the operation is IRREVERSIBLE, submits the document outside the organization to a tax authority, and cannot be recalled or undone through this API. It also advises user confirmation and content verification, which is critical behavioral context beyond destructiveHint=true.

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 critical irreversibility warning is effectively front-loaded, but the description is redundant: 'Report credit note to tax authority' appears three times in slightly different forms. The overall length is acceptable, but not every sentence earns its place.

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 destructive single-resource submission action, the description covers the essential operational context: external filing, irreversibility, user confirmation, and content checking. It omits post-submission behavior or expected response, but there is no output schema and the core requirements are well addressed.

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?

The schema documents idempotency_key in detail, but id has no schema description beyond 'string'. The description's endpoint 'POST /credit-notes/{id}/tax-authority/report/' implies id is the credit note ID, providing some compensation, but no additional parameter-level guidance or constraints are given.

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 states a specific verb ('Report') and resource ('credit note') and includes the explicit endpoint 'POST /credit-notes/{id}/tax-authority/report/'. It clearly distinguishes from sibling tax-authority report tools for invoices and simplified invoices by naming Credit Notes as the target document.

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 gives actionable usage context: confirm with the user before calling and check the document's contents first. It doesn't explicitly contrast with sibling report tools, but the resource-specific endpoint makes the intended use obvious enough.

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