triz_review_import

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

With no annotations the description carries the full burden, and it does disclose two useful traits: the operation is local-only, and review is an assertion over supplied ratings and assumptions rather than a verification of source correctness. It omits the observable state change (draft to reviewed) and the consequence that draft models cannot drive analysis, which is what an agent most needs to reason about effects.

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?

Three tight sentences, front-loading the local-only confirmation scope, then the procedure, then the epistemic caveat. Dense but every clause carries information; no filler or restatement of the title.

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 mutation tool over a very large nested model schema with no annotations and no output schema, the definition covers the decision payload well but leaves gaps: it does not say the argument model must include its provenance.pending list, nor what is returned (presumably the model now marked reviewed). Those omissions matter for a two-required-parameter write operation.

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 reported at 0% for the two top-level parameters, so the description must compensate. It does add real meaning for the decisions array — the id must be a currently pending id, each exactly once, decision is fixed to 'confirm', and note is optional — but says nothing about the 'model' parameter beyond 'edit the draft first', leaving the required full model payload unexplained.

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 a specific verb and resource: explicit analyst confirmation of an imported model, closing out its pending review items. It is distinguishable from the import-side sibling by the 'confirm every pending id with decision confirm' clause, though it never names triz_import_source or any other sibling directly.

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?

'Edit the draft first, then confirm every pending id exactly once' gives a clear precondition and ordering, so the agent knows this is the terminal step after editing, not a first move. It stops short of naming the specific tools to use for editing or where pending ids come from.

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