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

No annotations are provided, so the description carries the full burden. It implies a side-effecting capture against the currently active view but says nothing about permissions, latency, whether it overwrites a previous capture that revit_get_latest_screenshot would return, or any failure/threading behavior.

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?

A single, front-loaded sentence with no padding or redundancy. It is efficient but borders on under-specification given the tool's behavioral opacity.

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?

The output schema covers return values, and the capture target is stated. However, with no annotations, an unexplained port/doc_name pair, and no relation to the sibling screenshot tool, the definition leaves an agent guessing at how to invoke it correctly.

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% and neither 'port' nor 'doc_name' is mentioned in the description. The phrase "currently active view" implies no view-selection parameter, but the two actual parameters remain entirely unexplained, so the description does not compensate for the schema 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 states a specific verb pair ("triggers and captures") and resource ("high-resolution screenshot of the currently active view in Revit"), so the agent can tell what it produces. It does not explicitly name or distinguish itself from the near-identical sibling revit_get_latest_screenshot, leaving the capture-vs-retrieve distinction to inference.

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?

There is no explicit when-to-use guidance, no exclusions, and no reference to alternatives. The existence of a sibling revit_get_latest_screenshot makes the missing routing rule (capture now vs. fetch the last capture) a real gap.

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

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

With no annotations, the description must carry behavioral disclosure. It states execution occurs on the main UI thread and provides a transaction pattern for modifications, which are important behavioral traits. However, it does not mention permissions, side effects, error handling, or threading implications beyond 'main UI thread'.

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?

Bulleted list of available variables is concise and front-loaded with behavior. The transaction example is helpful but slightly verbose; however, it earns its place by showing a critical pattern. Overall efficient.

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 tool that executes arbitrary code, the description covers usage context (main thread) and a required pattern (Transaction) to prevent errors. It does not explain 'port' or 'doc_name' parameters, which is a gap, but with an output schema present, return values need not be described. Mostly complete but missing key parameter details.

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 0%, so the description must compensate. It explains the injected variables (doc, uidoc, etc.) but does not describe the 'code' parameter (beyond implied), 'port', or 'doc_name'—the latter two have no explanation at all. The description only partially addresses parameter semantics, leaving significant gaps.

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 specific action ('Executes arbitrary Python code inside Autodesk Revit on the main UI thread') and distinguishes itself from siblings like revit_list_instances or revit_get_selection, which are read-only. It doesn't explicitly compare, but the purpose is clear and unique.

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?

Provides critical context (main UI thread) and a required pattern for model modifications (Transaction), but does not say when to prefer this tool over others or what limitations exist (e.g., security, allowed modules). Implied usage for advanced scenarios, but no explicit alternatives or exclusions.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a safe read by saying 'Retrieves metadata' and hints at a multi-instance binding via 'the bound Revit instance', but it says nothing about permissions, error behavior, or what happens when no model is open.

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?

A single, front-loaded sentence with no filler; the returned fields are parenthetically listed efficiently. It is appropriately sized for the tool's scope.

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 the field enumeration in the description is helpful rather than necessary. However, given zero annotation coverage and zero parameter documentation, the description does not fully cover how to invoke the tool or what constraints apply.

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% and the description never references the two parameters (port, doc_name). The phrase 'bound Revit instance' weakly gestures at instance/port selection but does not explain how port or doc_name affect the lookup, leaving both parameters undocumented in both places.

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 specific verb (Retrieves) and resource (metadata about the currently open model) and enumerates the returned fields (title, file path, active view, level). It reads clearly as a read-only introspection call distinct from mutation-oriented siblings, though it does not name or contrast any sibling tool explicitly.

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?

There is no statement of when to use this tool versus alternatives such as revit_list_instances or revit_get_selection, nor any prerequisite conditions. Usage must be inferred purely from the tool name.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Retrieves' implies a read operation, but it does not state whether this requires an active document, user permissions, or whether any side effects occur. The returned field details are useful but overlap with the output schema.

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 description is a single front-loaded sentence with no wasted words. It states the core purpose and key output details efficiently.

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?

The output schema exists, so return value details need not be fully explained. However, with no annotations and no parameter descriptions in either the schema or the description, an agent lacks enough context about required document/port handling and optional element_ids behavior to invoke the tool confidently.

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% for all three parameters (port, doc_name, element_ids). The description says 'for elements' but never names or explains element_ids, doc_name, or port, so it does not compensate for the missing schema documentation.

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 uses a specific verb (Retrieves) and resource (geometric summary for elements) and enumerates the returned geometric details. It is clear enough to distinguish from sibling tools like selection or screenshot tools, but does not explicitly differentiate itself from all siblings.

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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The name and description imply a read operation, but the agent is left to infer the appropriate context.

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

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

No annotations are provided, so the description carries the full disclosure burden. It discloses the return content (metadata plus file path) and is implicitly read-only via 'Retrieves', but says nothing about behavior when no screenshot exists, error cases, or whether it reads from disk vs. app state.

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?

A single tight sentence with the outcome and returned data front-loaded and no redundant phrasing.

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 zero-parameter getter with an output schema that documents the return shape, the description covers purpose and payload adequately. It could add a note on the empty/no-screenshot case, but nothing critical is missing for correct invocation.

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?

Zero parameters, so there is nothing for the description to clarify beyond the schema; the baseline of 4 applies. The description correctly indicates the tool takes no input.

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 specific verb ('Retrieves') and resource ('most recently captured screenshot or user snip') plus the returned payload (metadata and file path). It distinguishes itself from capture-oriented siblings by emphasizing retrieval of the latest existing artifact rather than creating one, though it does not name any sibling explicitly.

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?

The phrase 'most recently captured' implies this is the post-capture fetch step, giving implied usage context, but the description never states when to prefer this over revit_capture_screenshot or revit_request_user_snip, nor any preconditions (e.g., requires a prior capture).

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not disclose what information is returned, whether the operation has side effects, permission requirements, or how the 'bound' document is determined. The only behavioral hint is 'currently selected,' which is minimal for a 2-param tool with zero annotation coverage.

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?

A single, front-loaded sentence that states the action and scope without waste. It is appropriately sized, though the emptiness of behavioral and parameter detail suggests the brevity reflects under-specification rather than optimal conciseness.

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?

Although an output schema exists (so return format needn't be described), the tool has two undocumented parameters and no annotations, and the description does not address either gap. For a tool that depends on the active document and selection state, more context is needed about prerequisites and parameter roles.

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 neither port nor doc_name is documented anywhere. The description does not mention either parameter, leaving the agent with no guidance on what port and doc_name mean or how they affect the result. Low coverage demands compensation that the description does not provide.

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 states a specific verb+resource: 'Retrieves information about currently selected elements in the bound Revit document.' This clearly distinguishes it from nearby siblings like revit_request_user_selection (which likely prompts the user to make a selection) and revit_get_element_geometry (which retrieves geometry rather than selection metadata). It is clear but does not explicitly draw the contrast with those siblings.

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?

The 'currently selected' phrasing implies the tool is used after a selection exists, but there is no explicit when/when-not guidance or mention of alternatives such as revit_request_user_selection. Usage context is implied rather than stated.

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

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

With no annotations, the description carries the full burden. It implies a read-only operation and references the 'bound' instance, but says nothing about connection requirements, what happens if no instance is bound, whether warnings are deduplicated/grouped, or any failure modes.

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?

A single, front-loaded sentence with no filler. It is efficient, though its brevity contributes to the gaps noted in other dimensions rather than being a pure virtue.

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, but for a 2-parameter tool with 0% schema coverage and no annotations, the description leaves the parameters, connection assumptions, and failure behavior undocumented.

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% for both port and doc_name, and the description never mentions them. The phrase 'bound Revit instance' hints at instance targeting but does not explain how port or doc_name select or override it, so the description fails to compensate for the coverage 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?

States a specific verb (Retrieves) and resource (active model warnings) scoped to the bound Revit instance, which is unique among siblings like revit_get_selection or revit_get_active_model. It does not explicitly contrast with any sibling, but the resource is distinct enough that no routing confusion arises.

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?

There is no guidance on when to call this versus alternatives, no prerequisites (e.g. must an instance be bound/active first?), and no exclusions. Usage is only implied by the verb 'Retrieves'.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the scan covers all ports and reports the bound instance, which is behavioral context beyond the name. However, it does not state the read-only nature explicitly, nor any auth/permission needs or limitations.

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?

A single front-loaded sentence with no wasted words. The scope and the bound-instance result are both stated in one pass.

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 zero-parameter read tool with an output schema, the description covers what the agent needs: it lists instances and identifies the bound one. Return-value details are delegated to the output schema, though a hint about when to call this versus revit_ping/revit_get_active_model is absent.

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?

The tool takes zero parameters, so the baseline is 4; there are no parameter semantics for the description to clarify. Schema coverage is 100% but irrelevant here.

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 specific verb 'Lists' and resource 'Autodesk Revit instances', plus scope 'across all ports' and the bound-instance indicator. It is clearly distinguishable from siblings like revit_set_active_instance, though it never names them explicitly.

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?

There is no explicit when-to-use or when-not-to-use guidance, but the purpose strongly implies discovery usage (finding instances before binding or targeting one). No alternatives are named, so usage remains inferred rather than directed.

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

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

With no annotations, the description must carry the full behavioral burden. It discloses that the tool checks connectivity and reports the active instance, implying a read-only diagnostic operation, but does not state whether it has side effects, requires authentication, or what the response contains beyond the active 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 description is a single, front-loaded sentence with no waste. It is appropriately sized for a simple diagnostic tool, though it could include a brief note on optional parameters without becoming verbose.

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 are covered. However, the description omits any explanation of the two optional parameters, leaving a gap for an agent deciding whether to pass port or doc_name.

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% for two optional parameters (port, doc_name). The description does not mention either parameter, so an agent receives no guidance on what they mean or when to supply them. The schema titles alone are minimal.

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 states a specific verb and resource: 'Checks connection health' and 'reports the active instance.' It is clear what the tool does, but it does not differentiate from siblings like revit_get_active_model, which may also report the active instance.

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?

No indication of when to use this tool versus alternatives such as revit_list_instances or revit_get_active_model. Usage is implied by 'checks connection health,' but no explicit context or exclusions are provided.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: the HUD button flashes and waits for clicks, single vs. multiple click semantics differ ('Finish' required for multiple), and the default wait is 90 seconds. It omits what happens on timeout (error vs. empty result) and whether the call blocks the agent for the full duration, which are the remaining gaps.

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 core action in the first sentence, followed by a compact Args block with no filler. The behavioral framing sentence and the parameter block both earn their space, though the description could be slightly tighter.

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 an interactive, annotation-free tool with an output schema (so return values need no explanation), the description covers the interaction mechanics and most parameters adequately. It is only short on timeout-outcome semantics and the undocumented port/doc_name parameters.

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 0%, so the description must compensate, and it documents four of six parameters with examples and defaults (prompt instruction, category filtering with ['Rooms','Walls'], multiple click behavior, timeout default). It leaves port and doc_name entirely unexplained, which matters for a multi-instance Revit tool, but the main parameters are well covered.

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 specific verb+resource ('requests the user in Autodesk Revit to select elements') and, via the HUD/'Pick Elements' detail, makes clear this is an interactive selection request rather than a read of existing selection. It never explicitly contrasts with the sibling revit_get_selection, so the agent must infer the distinction.

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?

The 'proactively requests' framing implies when the tool is appropriate (needing user input before continuing), but there is no explicit when-to-use vs. when-not guidance and no pointer to alternatives. Usage context is only implied.

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

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

With no annotations, the description carries the full burden. It does disclose the key behavioral trait that this is an interactive, user-driven operation requiring a human at the machine, which distinguishes it from automated siblings. However, it omits that the call blocks until the user finishes, what happens on timeout, and any output characteristics.

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?

A single front-loaded sentence with no filler or repetition. It is appropriately sized for what it attempts, though brevity here partly reflects under-specification rather than disciplined editing.

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 an interactive, blocking tool with no annotations and zero parameter documentation, the description is too thin: an agent cannot tell what the prompt is used for, how long it waits, or which document/instance it targets. The existing output schema covers return values, so that omission is forgivable, but the invocation contract is not.

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 four parameters (port, prompt, timeout, doc_name), so the description is the only place semantics could be added, and it adds none. The required 'prompt' string, the 90-second default timeout, and doc_name/port targeting are all left 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 states a specific verb (requests) and resource (the user in Revit to snip a screen region and annotate), which is clear and actionable. It does not, however, distinguish itself from closely related siblings such as revit_capture_screenshot or revit_request_user_selection, so an agent must infer the difference.

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?

There is no explicit when-to-use guidance and no mention of alternatives. The word 'proactively' hints that this triggers a user-facing interaction rather than an automated capture, but nothing tells the agent when to pick this over revit_capture_screenshot, which is exactly the ambiguity the description should resolve.

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

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

With no annotations, the description carries the full burden and does disclose the key behavioral trait: this mutates session-scoped routing state that affects every later call. However, it omits what happens if the port/title is invalid, whether the binding persists across sessions, and any concurrency or auth considerations.

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?

Two short sentences, no filler, with the core action and its consequence front-loaded. Every sentence 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 explained, and the effect on subsequent calls is covered. But for a state-mutating session-routing tool with zero annotations and 0% schema coverage on two optional params, the unresolved selection/precedence semantics leave the agent under-informed.

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 both parameters are documented only by the parenthetical 'by port or document title', which maps loosely to port and doc_name. It does not state whether the two are mutually exclusive, which wins if both are supplied, or that omitting both is legal (required=0, both nullable) — meaningfully ambiguous for a binding call.

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 specific verb ('Binds') and resource ('this session to a specific Revit instance/model'), plus the two selection keys (port, document title). An agent can distinguish it from siblings like revit_list_instances or revit_get_active_model, though the description never names those alternatives explicitly.

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?

The second sentence ('All subsequent operations will execute on this instance') implies this is a prerequisite/setup call, but there is no explicit guidance on when to call it versus revit_list_instances or revit_get_active_model, nor what to do if the binding fails. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full behavioral burden, yet it only states that visual state is set. It does not disclose whether this affects one or many instances (the 'port' parameter implies multi-instance targeting), whether state persists, or any side effects. This leaves significant gaps for a state-mutating tool.

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?

A single front-loaded sentence with no wasted words that states the core action immediately. Appropriately sized for the surface-level claim it makes.

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?

Although an output schema exists (so return values need not be described), the 0% parameter coverage and absence of annotations mean the description should explain the five parameters and behavioral traits but does not. It is far too thin for a five-parameter mutating tool.

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 five parameters, so the description must compensate. It only obliquely maps to 'busy' and mentions a 'background color' that has no corresponding parameter, leaving port, message, activity, and doc_name entirely 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?

States a specific verb ('Sets') and resource ('visual busy indicator and background color of the Revit MCP HUD'), which is clearly distinct from siblings like revit_capture_screenshot or revit_ping. It does not explicitly differentiate itself from siblings, but the HUD/UI-state domain makes its role unambiguous.

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?

The description offers no when-to-use guidance, no prerequisites, and does not mention any alternative or related tool. An agent has no signal for when toggling the busy indicator is appropriate versus other Revit tools.

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