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

No annotations exist, so the description carries the full burden and does so: it states the entry is a draft, that it does not touch the books until …/post, that source_ref_type/source_ref_id are defaulted by pipeline paths only, that document_id is the retrofit attach (also available post-creation on a posted entry), and that auto_reverse_date must be after posting_date (422 otherwise) and can only be set while draft. That is exactly the mutation/permission/reversibility context an agent needs.

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?

Long but front-loaded with the crucial 'draft / no source document' fact, then the routing alternatives, then the auto_reverse constraint. The bulleted sibling routing is dense and earns its space, though the prose around the document attach paths is slightly repetitive.

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 complex 9-param mutation tool with no annotations and no output schema, the description covers creation semantics, draft/post lifecycle, evidence attachment, and auto-reversal well. It stops short of explaining the line structure (line_role semantics, amount_base vs amount_currency, open_item behavior beyond the schema snippet), leaving a gap for the core booking payload.

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, so the description must compensate; it thoroughly explains document_id and auto_reverse_date (constraints, timing, 422), but leaves entry_type (13-value enum), line_role (16-value enum), the lines array shape, currency, period_id, company_id, and description field unexplained. Partial compensation for a 9-parameter tool.

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 + resource (create a *draft* journal entry by hand) and immediately nails the distinguishing trait: no source document unless one is named. This lets an agent separate it from post_gl_journal_entry and the ingestion/coding siblings without opening a 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?

Explicit when-to-use (reclassifications, provisions, accruals, year-end adjustments) and when-not ('Do not transcribe a document into it and then attach the file'), then routes each document-backed case to the correct sibling endpoint (uploads/intake → autopost-decisions, items/{id}/coding, bank-entries/manual-coding, opening-entries). Nothing is left to inference.

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