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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely non-derivable behavior: apps-capable hosts render a contract browser while other clients get the same JSON, so output shape varies by host; and reads stay available when the tracking plan lapses, telling the agent this call is not gated by subscription state.

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?

Roughly five short clauses, front-loaded with the action triage, which is the highest-value information. Every sentence carries signal, though the tracking-plan-lapse and host-rendering notes are secondary and could be ordered after the action guidance.

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 15-parameter, three-action tool with no output schema, the description covers mode selection, cross-tool ordering, host-dependent output, and date semantics. Remaining gaps — pagination behavior and what 'related' actually returns — are partly mitigated by 80% schema coverage, but the absence of an output schema means the return shape of get/related is left to inference.

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 80%, so the schema already carries most parameter meaning (sort default, per_page max, status pattern, ending_within_days timezone). The description's only added semantic is that contract lifecycle dates are distinct from signing deadlines, which helps disambiguate the end_date filters but does not explain any individual parameter or which filters apply to which action.

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 the resource (contracts) and enumerates the three modes the single tool dispatches to: 'list' with filters, 'get' for terms or one amendment, and 'related' for a root plus its amendments. That maps cleanly onto the oneOf schema and lets an agent pick a mode without opening the schema. It stops short of naming any sibling (e.g. assinafy_list_documents) to contrast against.

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?

It gives clear per-action guidance — use 'get' for terms or an amendment, 'related' for a root and its amendments — and adds a cross-tool rule, 'Resolve names before writes', which steers the agent to browse before calling update_contract. There is no explicit when-not or statement of which sibling handles a different case, so it falls short of the 5 bar.

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