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

Beyond the annotations, the description adds two concrete behavioral guarantees: it preserves the original analysis revision and never calls a drafting model. This is useful and does not contradict destructiveHint=true, since the operation may still overwrite an existing matrix while leaving the analysis revision intact.

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?

Two tight sentences with no filler; the core purpose is front-loaded and the two behavioral caveats are packed into the second sentence without burying the main point.

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?

The description and schema are adequate for a basic call, but with no output schema the return behavior is unstated, and the destructiveHint=true annotation leaves whether an existing matrix is overwritten to inference. It also does not explain how the optional CSV/TSV maps to matrixText or how selectedClaimVersionIds interacts with the dossier analysis.

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 67%: projectId and idempotencyKey are documented, while the nested matrix object is not described at the property level. The description hints that matrixText can hold pasted CSV/TSV content, but it does not explain title, sourceFileName, or selectedClaimVersionIds beyond their schema constraints.

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 states a specific action ('Build') on a specific resource ('review matrix') with clear inputs ('current dossier analysis and optional pasted CSV/TSV'). This distinguishes it from read-oriented siblings like read_compliance_matrix and change-request tools such as request_matrix_changes.

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?

The first sentence makes the context explicit: use this when constructing a matrix from the current dossier analysis, optionally incorporating pasted CSV/TSV data. It does not name alternatives or exclusions, but the build-vs-read distinction is clear enough for an agent to select it appropriately.

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