Capture Elements

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is partly covered, yet the description adds meaningful non-obvious behavior: the temporary view is rolled back without changing the active view or model, local vs SSH transport is supported, and incomplete results are signaled via non-empty skipped with skippedCount capped past the first 100. This is genuinely useful context beyond the annotations, though it omits auth/permission needs.

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?

Purpose is front-loaded in the first sentence, followed by return format, capability envelope, and rollback/skipped caveats. Nearly every sentence carries operational information. The fragmented paragraph breaks are slightly choppy but nothing is wasted.

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 7-parameter capture tool with no output schema, the description covers the return payload (PNG plus data.localPath), the transport modes, the multi-instance document requirement, and the skipped/skippedCount completeness signal. Only padding_mm semantics and any permission requirements are left unaddressed, so it is close to complete.

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?

With 57% schema coverage the schema already documents save_to, document, pixel_size and process_id, but the description adds key constraints the schema lacks: the 1 to 500 bound on element_ids and the 3d/plan values for mode. It leaves padding_mm unexplained, so it does not fully compensate for the coverage gap, keeping it at 4.

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?

States a precise verb+resource+output: 'Show where specific elements are in a highlighted PNG for issue evidence', and confirms the return payload ('PNG image content and data.localPath on the server machine'). This clearly separates it from pure data-query siblings like revit_query_elements or revit_element_details. It stops short of naming a sibling it is not, so it lands at 4 rather than 5.

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?

Gives situational context ('for issue evidence') and one hard precondition (document is required when more than one Revit instance is running; otherwise any instance may respond). However it never names an alternative such as the non-image revit_show/revit_isolate highlighters or revit_export_view, so the agent must infer when to prefer a PNG capture over those siblings.

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