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

Goes well beyond the annotations: it discloses that the booking is recorded as Lovie Agent's proposal, that nothing changes until the person accepts it, that the agent should tell the user it is awaiting review, and that the return value is proposal_id. The annotations only say non-destructive and idempotent, which on their own would not reveal this proposal/acceptance workflow.

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?

Six short sentences, front-loaded with the action and ending with the batch routing. The bulk of the length is justified by the proposal-workflow disclosure, though the account-mapping sentence is marginally less essential than the rest.

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?

Output schema exists so return shape need not be spelled out, yet the description helpfully names proposal_id anyway. It covers sourcing, side effects, user messaging, and the batch alternative; the only real gap is the undocumented origin enum and nested category wrapper, which matter for correct invocation.

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 50%, and the description only adds meaning for the category parameter (where to source it). It says nothing about the origin enum, the companyId/transactionId UUID wrappers, or the category key/ownerKey/ownerType structure, so half the parameters remain explained only by the schema.

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 ('Give one transaction a Category') and explicitly contrasts with the batch sibling at the end. An agent can distinguish this from transaction_batch_assign_transaction_category and transaction_suggest_transaction_category without opening any 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?

Names the two valid sources for the category argument (transaction_get_list_assignable_categories and transaction_suggest_transaction_category) and the explicit when-to-use-which condition for the batch alternative ('For several transactions use transaction_batch_assign_transaction_category').

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