Run My Tool

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real operator context beyond them: confirm_token is required on the first run per session even for read/dry_run, read/dry_run roll back, transaction=group wraps script-owned transactions in one Undo group, and timeouts can occur after a commit has landed. The "two-step AI app token handshake" is named but never explained, which keeps it from a 5.

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 text is short but written as terse fragments that shift topic each sentence, moving from execution to token handshake to transaction grouping to timeouts. The most important constraint, the confirm_token requirement, is not front-loaded, and jargon like "execute_code gates" and "token handshake" is used without definition.

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 explained, and the description covers the confirmation and transaction mechanics an agent must understand for a destructive runner. However, with 7 parameters at 0% schema coverage and a nested args object, leaving name/args/document undefined is a meaningful gap for a tool that executes arbitrary saved C#.

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% across 7 parameters, so the description should be carrying more weight. It does explain confirm_token, dry_run and transaction=group semantics, and implies timeout behavior, but name, args (the required nested object) and document are never described at all.

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?

"Run saved C#" names a specific verb and resource, and the sibling list contains revit_save_tool, revit_get_tool, revit_list_tools and revit_execute_code, so an agent can infer this executes a previously stored tool rather than ad-hoc code. It never explicitly states the saved-tool relationship or how it differs from revit_execute_code/revit_run_actions, so it falls short of full sibling differentiation.

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 conditional prerequisites rather than when-to-use guidance: first run per session needs confirm_token, action commits need a token, and store runs require a machine-level ExecuteCode=confirm. Nothing tells the agent when to pick this over revit_execute_code or revit_run_actions, which is the main competing choice in the sibling list.

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