register_contract_to_cash_invoice_issued

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

Annotations already convey readOnly=false, idempotent=true, and destructive=false. The description adds useful framing: 'seal' and 'custody' imply an immutable internal evidence write rather than a live QuickBooks mutation. However, it does not mention the approval_required=true and authoritative_write_authorized=false constraints visible in the schema, which are material behavioral traits for an agent.

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 front-loaded sentence with no filler words. It is appropriately short, though the phrase 'exact reconciled QuickBooks issuance evidence' is dense and jargon-heavy, making it slightly less crisp than it could be.

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 with a large nested schema, three required parameters, and workflow-sensitive semantics like approval_required and requested_effect, one poetic line is insufficient. The presence of an output schema reduces the need to document return values, but the tool still lacks guidance on prerequisites, workflow ordering, and the meaning of 'custody' in operational terms.

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% at the top level, and the description contributes nothing about company_ref, project_ref, or request. The nested schema's names and constants are self-explanatory to some degree, but the description does not compensate for the absence of parameter-level guidance on how to construct a valid admission.

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 names a concrete action ('seal'), a resource ('exact reconciled QuickBooks issuance evidence'), and a destination ('Spring custody'). It is domain-specific and helps separate this tool from siblings like execute_contract_to_cash_invoice or get_contract_to_cash_invoice_issued, though the metaphorical verb 'seal' is less direct than 'register' or 'record'.

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?

No when-to-use or when-not-to-use guidance is provided. The description does not mention how this relates to sibling flows such as attach_contract_to_cash_invoice_issued, register_contract_to_cash_cash_collection, or execute_contract_to_cash_invoice, leaving the agent to infer the intended workflow position from the name alone.

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