transaction

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

With no annotations, the description carries the burden and does real work: it discloses that abort rolls back EVERYTHING since begin 'in one step', and that the name surfaces in Inventor's undo list. Undisclosed: nesting behavior, lifetime/scope of the transaction across tool calls, and whether it is bound to a document or instance.

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?

The purpose is front-loaded in one line, followed by a tight Args block with no filler. The docstring formatting is slightly atypical for a tool description but each element earns its place.

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?

An output schema exists so return values need not be described, and the core begin/commit/abort lifecycle is covered. For a stateful mutation-control tool with zero annotations, though, it should say what scope the transaction spans (document vs. session, per instance) and what failure modes abort produces.

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 only 33% (only 'instance' is documented), so the description must compensate. It does explain the three meaningful values of 'action' and the purpose of 'name' (undo-list label), which is the highest-value addition. However it says nothing about 'instance' scope or which operations are actually captured, leaving partial coverage.

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 opening sentence names a concrete mechanism (an undo/rollback unit wrapping multiple operations), which is far more specific than the bare name 'transaction'. It does not explicitly contrast itself with any sibling, but no sibling in the list offers transactional/rollback semantics, so confusion risk is low.

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 per-action guidance: begin 'before a risky multi-step build', then commit on success or abort on failure. That is genuine when-to-use instruction tied to each action value, rather than vague framing. It stops short of stating prerequisites (e.g. whether a transaction must be started before mutating tools, or what happens if begin is called twice).

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