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

Annotations already cover read-only/idempotent/non-destructive, and the description adds much more: matching is by registry identifier alone, the name column is echoed but never used to match, the full outcome vocabulary (add, reactivate, in_book, duplicate, ambiguous, unresolved, invalid), and that counts/total always span the whole file.

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?

Dense but front-loaded: purpose first, then CSV contract, then matching rule, then per-row output, then paging. No sentence is filler, though the single long block is heavier than strictly necessary.

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?

No output schema exists, so the description carries the return burden and does so: each row returns an outcome, reason, matched node_id and register name, plus paging termination guidance ('page on until offset reaches total'). Nothing needed to call or interpret it is missing.

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?

Well past the 100%-coverage baseline: it specifies the CSV header (identifier_type,identifier plus optional name, currency, limit_amount, drawn_amount), the accepted identifier_type values (lei, uk_crn, de_register with register type/number/court, us_cik, other national schemes), the 2,000-row cap, and how limit/offset page in file order with total covering the whole file.

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?

Specific verb+resource: 'Preview adding a book of companies to the caller team's monitored portfolio.' It also implicitly separates itself from the apply path by pointing at the dashboard, so the agent can distinguish preview from any write-side sibling.

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 states the context ('preview adding a book') and the exclusion ('Nothing is written, and applying an import happens in the Stonewake dashboard'). It does not name a sibling tool as the alternative, but the dashboard reference makes the when/when-not clear.

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