Process Many Models

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

Annotations already flag destructive=true and idempotent=false, but the description adds real behavior beyond them: the confirm_token gate for in-place writes, the async status=running + jobId return when the wait budget expires, the risk that the model was already modified, and the non-idempotent resubmit warning. This is substantive transparency for a long-running destructive batch job.

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?

Front-loaded with the pipeline in the first sentence, then layered with the gating, async, and resubmit notes. Four dense sentences with no filler. Slightly overloaded, but every clause carries information.

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 re-explained, yet the description still usefully flags the status=running/jobId shape. For a 14-parameter, destructive, 500-model batch tool it omits dry_run guidance and any sibling differentiation against revit_run_actions/revit_batch_start, leaving meaningful gaps.

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 0%, so the description must carry the load and only partially does. It explains confirm_token's provenance and that code/in-place saves require it, and implicitly covers open/save/exports via the pipeline sentence. It says nothing about dry_run, paths, folder, pattern, recursive, stop_on_error, process_id, or timeout_seconds, and the self-documenting nested enums (mode, format) do not close that gap.

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 resource (many models) and enumerates the pipeline it runs: open, run steps and C# code, export, save, close. An agent immediately knows this is a multi-model batch executor. It does not, however, distinguish itself from close siblings like revit_run_actions or revit_batch_start, which cover overlapping ground.

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 states a concrete prerequisite (confirm_token from the preview response for in-place saves and code) and warns that resubmitting repeats the action. But there is no explicit when-to-use vs revit_run_actions, revit_execute_code, or revit_batch_start, nor any guidance on dry_run. Usage is implied rather than routed.

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