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

Annotations confirm it is a non-readOnly, non-idempotent write, and the description goes well beyond them: new rows land status='unapproved' and wait in the Review tab, approve=True is recorded under the user's name and listed as 'settled without review', is reversible with one click, and is refused 403 unless the user has approve rights. It also discloses that the response may carry validation_errors and near_duplicates and tells the agent to surface them rather than ignore them.

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?

Front-loaded with the action, then parameter meanings, then the gated approve behavior, then response caveats, in the order an agent needs them. It is long but dense with decision-relevant detail for a 5-parameter write tool with nested structures; no sentence is filler.

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?

Given a write tool with nested objects, no schema descriptions, and a highly consequential approve flag, the description covers nearly everything: prerequisites, per-parameter meaning, side effects, permission failures, and response warnings. Minor gap: it does not describe the success payload or confirm what a successful load returns, though the output schema partly carries that.

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%, so the description carries the full burden and does: memory is defined as the graph's slug, results as a map of pass key to pass JSON with a concrete example, source_doc and source_title explained with an example filename, and approve given conditional semantics. It additionally documents the nested evidence shape ({quote, page, section}, quote verbatim) that the schema leaves opaque.

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 ('Save the extraction you produced') and situates it precisely in the workflow as the LAST step after get_extraction_prompt and resolve_names, which cleanly separates it from those siblings. An agent can tell exactly what this tool does and where it belongs in the sequence.

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?

Explicitly names the preceding steps it must follow, and draws a hard line on the alternative for approve: only when the user explicitly says to load as approved, 'Never set it on your own judgement'. It also names the fallback path ('then load without it') when approval is refused with 403.

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