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

Annotations already declare readOnlyHint=true, so the description's 'handshake ping' adds mild behavioral context (non-destructive). However, it does not discuss rate limits or 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?

The description is a single concise sentence that efficiently conveys the tool's essence without extraneous 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?

For a simple ping tool with an output schema, the description is too sparse. It fails to mention what the output indicates (success/failure) or error handling, leaving the agent underinformed.

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 provides no explanation of the 'pid' parameter. The agent cannot infer what the integer represents or how to use it.

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 clearly states it is a 'handshake ping' to verify plugin listener responsiveness, which is a specific and distinct purpose. It distinguishes from sibling tools that perform other functions.

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 guidance on when to use this tool or when not to. Lacks mention of prerequisites or alternatives, leaving the agent without usage 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?

The annotations include destructiveHint: true, but the description adds no context beyond 'toggles visibility'. It fails to explain what the destructive nature refers to (e.g., state reset, data loss) or any side effects, leaving the agent without critical behavioral insight.

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 extremely concise at one sentence. While it lacks detail, it is front-loaded and direct, with no wasted words. However, it could be longer to add necessary context without sacrificing 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?

Given the tool has two required parameters and an output schema, the description is insufficient. It does not explain what the parameters mean (e.g., pid identifier, is_available toggles to true/false), nor does it describe the return value. The destructive hint is not addressed, making the overall completeness low.

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 input schema has 0% description coverage for its two required parameters (pid, is_available). The description provides no additional meaning or constraints for these parameters, leaving their purpose ambiguous.

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 'toggles' and identifies the resource 'visibility of the PyNet log/output window'. It clearly distinguishes the tool's function from sibling tools like get_output_window_status, which likely reads the status without modifying it.

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 guidance is provided on when to use this tool versus alternatives such as get_output_window_status. The description does not mention prerequisites, context, or when not to use it.

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?

Annotations already provide destructiveHint. The description adds minimal behavioral context beyond 'creates', such as effects on existing modules or permissions needed.

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 sentence is concise but lacks necessary detail, achieving a middle ground.

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?

Given only 1 sentence and no parameter info, the description is incomplete for a 2-parameter 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%, but the description does not explain the parameters (pid, name) at all, leaving the agent without semantic clues.

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 clearly states the action 'Creates' and the resource 'new custom Tab (ButtonsModule) in the Ribbon', distinguishing it from siblings like delete_pynet_module.

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 guidance on when to use or alternatives. Lacks context for decision-making.

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?

The description adds 'permanently' to the existing destructiveHint annotation, emphasizing irreversibility but not disclosing other traits like required permissions or effects on dependencies. The annotation already signals destructiveness, so the description adds minimal new insight.

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 7-word sentence, very concise. However, it is too brief to inform the agent adequately, sacrificing substance for brevity.

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 destructive tool with two required parameters, the description lacks important context such as error handling (e.g., if module doesn't exist), dependencies, and whether the deletion cascades. An output schema exists but does not compensate for missing behavioral context.

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 description does not explain the parameters 'pid' and 'module_id' beyond what is in the schema. With 0% schema description coverage, the tool relies entirely on the description for parameter meaning, which it fails to 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 the tool deletes a module and all its contents, clearly specifying the verb 'delete' and resource 'module'. However, it does not differentiate from sibling tools like 'delete_script_button', which also delete but on different resources.

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 guidance is provided on when to use this tool versus alternatives, such as the sibling tools that also perform deletions. There is no mention of prerequisites or conditions.

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?

The annotation already provides 'destructiveHint: true', which signals destructiveness. The description adds 'permanently removes', consistent with the annotation. However, it does not disclose additional behavioral details like required permissions, cascading effects on other data, or error conditions. The annotation carries most of the burden here.

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 sentence with no superfluous words. It is front-loaded with the action and resource. Every word 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?

Given the tool has three required parameters with no descriptions and a destructive action, the description should provide more context about the removal process, return value, or prerequisites. The output schema is present but its content is unknown; the description does not compensate for the lack of parameter documentation.

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 input schema has 0% description coverage on parameters, and the description only says 'by Id', failing to explain what each parameter represents (e.g., pid likely a project ID, module_id a module, button_id the button identifier). The field names offer some clue but are insufficient for an agent to correctly map parameters without additional context.

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 clearly states that the tool 'permanently removes a ScriptButton from a module by Id'. It uses a specific verb ('removes'), identifies the resource ('ScriptButton'), and specifies the scope ('from a module by Id'). This distinguishes it from siblings like 'deploy_script_button' (create) and 'update_script_button' (modify).

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 provides no explicit guidance on when to use this tool versus alternatives like 'deploy_script_button' or 'update_script_button'. It does not mention prerequisites, when not to use, or how it fits into a workflow. The word 'permanently' hints at irreversibility but is not a substitute for explicit guidelines.

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?

Annotations mark destructiveHint=true, but description doesn't disclose what makes it destructive (e.g., overwriting existing buttons). No contradiction, but missing detail.

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?

Single sentence with 10 words, no fluff. Clearly states purpose.

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?

With 6 parameters, a destructive hint, and an output schema, the description is too sparse. Does not explain critical parameters like pid and module_id, nor return behavior.

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%, but description lists Name, Script, Icon, Tooltip which helps map to parameters. However, pid and module_id remain 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?

Description uses specific verb 'Installs' with clear resource 'ScriptButton into a specific module', and mentions parameters in parentheses. Distinct from sibling tools like update_script_button.

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 guidance on when to use this tool vs alternatives like update_script_button or delete_script_button. Doesn't mention prerequisites or 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?

Annotations already declare readOnlyHint=true, so the description adds little beyond that. It mentions the tool lists buttons by module ID, which is consistent but not additional behavioral context.

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?

Single sentence, concise and front-loaded. No unnecessary words.

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?

Description is minimal given two parameters without explanation. Output schema exists but is not shown; return values may be documented there. However, more context about the purpose of pid would improve completeness.

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%; description does not explain the parameters pid or module_id beyond implying module_id is the module ID. With low coverage, the description fails to add meaning to the parameters.

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?

Description clearly states verb 'Lists' and resource 'script buttons' with a qualifier 'for a specific module ID'. It is specific and distinguishes from sibling tools like delete_script_button or deploy_script_button.

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 explicit when-to-use or when-not-to-use guidance. However, the read-only nature is implied by the description and annotations, distinguishing it from mutation tools among siblings.

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?

Annotations already declare readOnlyHint=true. Description adds minimal context about checking availability/visibility, but does not specify return format or edge cases. Adequate but not comprehensive.

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?

Single sentence with no wasted words. Front-loaded and 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 simple tool with a single parameter and an output schema, the description is minimal but acceptable. However, the lack of parameter explanation and return value context leaves room for improvement.

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% with no parameter descriptions. The description does not mention the 'pid' parameter, leaving the agent without any context on what value to 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 clearly states the verb 'checks' and the resource 'output window status' with specific scope 'available/visible'. It uniquely distinguishes this tool from sibling tools like viewer_status or check_plugin_status.

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 guidance on when to use this tool versus alternatives. No mention of prerequisites or context. Usage context is implied from the tool name alone.

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?

Annotations provide readOnlyHint=true, so the tool is safe. The description adds context about the fetched content (ButtonsModules and ScriptButtons). It does not disclose potential errors, performance implications, or authorization needs, but annotations cover the safety aspect.

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 concise sentence, front-loaded with the core action. No wasted words.

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?

While the output schema exists, the description omits explanation of the required 'pid' parameter. It also lacks comparison with sibling tools. For a tool with one required parameter, this is insufficient.

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 does not explain the 'pid' parameter. The agent has no information about what 'pid' represents or how to use it.

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 clearly states the tool fetches the full UI structure (ButtonsModules and ScriptButtons). The verb 'Fetches' and resource are specific, but it does not explicitly differentiate from sibling tools like 'get_buttons_data'.

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 guidance is provided on when to use this tool versus alternatives. The description implies it is for obtaining the full UI layout, but does not mention exclusions or context (e.g., compare with get_buttons_data).

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?

Annotations already provide readOnlyHint=true, and description adds behavioral context by specifying the condition of an active PyNet IPC pipe, which is valuable beyond the annotation. No contradictions.

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?

Single sentence, front-loaded with action, no unnecessary words. Highly 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?

Given zero parameters and an existing output schema, the description fully explains the tool's purpose and behavior. It is complete for an agent to invoke without additional context.

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?

No parameters exist, so schema coverage is 100%. The description adds meaning by defining the scope of scanning (processes with active pipe), which compensates for the absence of parameters.

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?

Description clearly specifies the verb 'scans' and the resource 'running Autodesk processes with an active PyNet IPC pipe', distinguishing it from sibling tools which focus on plugin, UI, or viewer operations.

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 explicit guidance on when to use this tool versus alternatives. While sibling tools are different, the description implies its usage for discovering active instances, but no when-not-to or prerequisites are 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?

Annotations already mark destructiveHint=true; description adds 'direct script execution' but lacks details on side effects or permissions beyond annotation.

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?

Single sentence with parenthetical list; efficient but could better structure parameter explanation.

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?

Destructive tool with 4 required params and no schema descriptions; description lacks scripting constraints, output explanation, and usage context despite having an output schema.

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 0% schema coverage, description mentions pid, script_name, content but omits timeout and offers no format/type guidance for content or script_name.

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?

Clearly states verb 'execute' and resource 'script' with key parameters (PID, Script Name, Content), distinguishing from sibling send_command_by_path which uses path instead of PID.

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?

Implies usage for direct script execution by PID but provides no explicit conditions or comparison with alternative send_command_by_path.

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?

Description aligns with annotations (destructiveHint=true) and adds the behavioral distinction of executing via path vs inline. However, it does not disclose other traits like authentication needs, rate limits, or side effects beyond execution.

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?

Single sentence that is front-loaded and efficient, with no wasted words.

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?

Despite having an output schema (not shown), the description omits critical context for a destructive, path-based execution tool: file existence, permissions, error handling, and typical usage scenarios. This is inadequate given the tool's complexity.

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 has 0% description coverage, and the description provides no meaning for any of the 4 required parameters (pid, script_name, file_path, timeout). The agent must infer solely from parameter names, which is insufficient for correct invocation.

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?

Description clearly states the action ('Executes a script file directly by path') and the resource ('in the PyNet engine'), and contrasts with inline sending, distinguishing it from sibling tool 'send_command'.

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?

Implied usage when a script file path is available, but no explicit guidance on when to use this tool versus alternatives like send_command, nor any exclusions or prerequisites.

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?

The annotations already declare destructiveHint=true, and the description confirms mutation by using 'updates' and 'moves'. However, no additional behavioral details are given (e.g., authorization requirements, side effects, or rollback capabilities), so the description adds limited value beyond the annotation.

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 sentence that efficiently communicates the two core functions upfront. There is no redundant information, and every word contributes to understanding the tool's purpose.

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?

Despite having 8 parameters (7 required) and an output schema, the description does not clarify parameter groupings, the optional nature of dest_module_id for moving, or what the output contains. An agent would need additional context to use the tool 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?

With 0% schema description coverage, the description should compensate but only weakly connects 'metadata' to parameters like name, tooltip, and icon_name, and 'move' to dest_module_id. It does not explain the role of each parameter or provide examples, leaving the agent to infer the mapping.

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 clearly states two specific actions (updating metadata and moving to another module) with a concrete resource (ScriptButton). It effectively distinguishes from sibling tools like delete_script_button and deploy_script_button by specifying the operations that are unique to this tool.

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 implies usage for updating or moving a ScriptButton, but it does not explicitly state when to use this tool versus alternatives such as delete_script_button or deploy_script_button. No exclusions or context-specific guidance is 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?

Annotations declare readOnlyHint: true, but the operation modifies the viewer's visual state. The description does not elaborate on side effects or whether the action is reversible. However, it is clear that it removes existing highlights/ghosting.

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, informative sentence with no unnecessary words. It front-loads the core action and object.

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 simple tool with no parameters and an output schema, the description is sufficient. It could be improved by noting that it affects only the open viewer.

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 has no parameters, so the baseline is 4. The description does not need to add parameter details since the schema is empty and 100% 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?

The description clearly states the specific action ('clears') and the target resource ('highlights and ghosting in the open viewer'). It distinguishes from sibling tools like viewer_highlight_clash and viewer_isolate.

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 explicit guidance on when to use this tool versus alternatives. The description implies it should be used after highlights or ghosting are applied, but does not mention prerequisites or scenarios.

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?

Annotations already indicate readOnlyHint=true, so the read-only safety is covered. The description adds value by specifying that the camera fits to 'all models' (not just selected), which is a behavioral trait. No contradictions.

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 sentence that is perfectly front-loaded and contains no fluff. Every word 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?

Given the tool has no parameters, simple action, and an output schema (mentioned in context), the description is complete. An agent can understand exactly what the tool does without additional context.

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?

There are zero parameters, and schema coverage is 100% trivially. The description does not need to add parameter details. Baseline 4 is appropriate for no parameters.

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 clearly states the action ('fits the camera') and the target ('all models in the open viewer'), distinguishing it from sibling tools like 'viewer_isolate' or 'viewer_clear'. The verb 'fits' is slightly technical but specific enough for an AI agent.

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 provides no guidance on when to use this tool vs alternatives like 'viewer_isolate' or 'viewer_select'. It lacks context for prerequisites or situations where this tool is appropriate.

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?

Annotations only declare readOnlyHint, so the description carries most of the burden and fills it well: it discloses the return shape of each mode (full psets vs pnt_id/name/model index), the default page size (200) and hard cap (500), the scale risk on federated models (tens of thousands of entries), and the crucial provenance constraint that data comes from properties.json rather than the viewer or IFC.

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?

Content is front-loaded on the core read behavior, then mode-specific guidance, then the data-source caveat. It is four paragraphs and slightly longer than strictly necessary, but each paragraph adds distinct, non-redundant information, so no sentence 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?

Covers both invocation modes, filtering, pagination, scale caveats, and the data source; an output schema exists so return values need not be explained. Nothing required to call this read-only tool correctly is missing.

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 compensate and does: pnt_ids as full-property lookup keys, model as an exact model/discipline name with a concrete example, search as a case-insensitive substring of element name, and limit/offset semantics including the 200 default and 500 cap. Every parameter gains meaning beyond its bare title and type.

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 and resource ('Reads element properties ... from properties.json') and clearly splits behavior into two modes (pnt_ids for full properties, no pnt_ids for a lightweight paginated index). It does not name any sibling tool, so the differentiation from tools like viewer_get_state or viewer_list_clashes is left implicit.

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 explicit branch conditions: pass one or more pnt_ids for full properties, call with no pnt_ids for the index. It further instructs to narrow with model and/or search, page with limit/offset, and warns to 'always pass model or search when you can' on federated models. This is actionable when-to-use guidance with a concrete heuristic.

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 readOnlyHint=true already declaring the safety profile, the description still earns credit by disclosing the null-if-nothing-selected behavior and the source of the selection (3D view click or tree panel). It stops short of describing refresh semantics (is state 'last reported' cached or live), which matters for a state reader.

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 tight sentences: the first defines the return payload, the second routes the agent onward. Nothing is redundant and the payload definition is front-loaded.

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 and the description anyway names the key fields plus the null condition, so an agent can act immediately. For a zero-param read tool, nothing material is missing.

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 disambiguate; the schema and description are consistent. Baseline 4 applies.

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 ('reads') and resource ('viewer's last reported state'), and enumerates the payload (loaded models, selected pnt_id). It does not, however, distinguish itself from the sibling viewer_status, which by name may return overlapping state information.

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?

Clearly frames the tool's role in a workflow — take the returned pnt_id to viewer_get_properties for details, or into a clashes.json lookup. That is strong downstream guidance, but it never states when to prefer this over viewer_status or viewer_get_properties directly.

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?

Annotations supply only destructiveHint=true; the description adds genuinely new behavioral context: the red/green coloring, that everything else is isolated away (which explains the viewer-state mutation behind the destructive hint), and that lists are accepted on either side. It does not discuss whether the prior view state is recoverable, but it substantially enriches the thin annotation set.

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 sentences, front-loaded with the core action and color mapping, then the cardinality nuance. No wasted wording, though the parenthetical list example is slightly 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?

Output schema exists so return values need no explanation, and the parameters are covered. What is missing is routing guidance against the many viewer_* siblings and any note on how destructive the isolation is to the current view state.

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% and neither pnt_id_a nor pnt_id_b is described in the schema, but the description compensates well by mapping A to red and B to green and clarifying the string-or-list shape of both. This is close to the full meaning an agent needs, though it never explains what a pnt_id refers to.

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 (highlights) and resource (a clash), plus the exact visual semantics — element(s) A red, element(s) B green — and the side effect of isolating everything else. An agent can distinguish this from viewer_isolate and viewer_select on the color/isolate behavior alone.

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 explains how the parameters behave (one id per side vs a list) but never states when to reach for this tool instead of viewer_isolate, viewer_select, or viewer_list_clashes. No prerequisites or exclusions are given.

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?

Annotations declare destructiveHint=true, and the description usefully clarifies the semantics of isolation (that everything else becomes hidden), which is meaningful context for a mutation of viewer state. It does not, however, say how to restore visibility (viewer_clear/viewer_fit) or that isolation replaces prior visibility 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, front-loaded sentence with zero wasted words, and the parenthetical definition is placed immediately where it is needed.

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. For a one-parameter viewer operation the description is largely adequate, though it omits the prerequisite of an open viewer and the interaction with sibling viewer operations.

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 there is one parameter, so the description must compensate. It names the parameter (pnt_ids) and implies its meaning (point/entity IDs to keep visible), but provides no format, source, or behavior when the array is empty. Baseline 3 is appropriate given the partial compensation.

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 (isolates) and resource (the given pnt_ids in the open viewer) and even parenthetically defines what 'isolates' means (hides everything except). Distinguishable from the sibling viewer_isolate_models, which operates on models rather than pnt_ids.

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 implies the tool is a viewer filter operation but gives no explicit when-to-use guidance, no prerequisite (a viewer must be open), and never names the alternative viewer_isolate_models. The distinction from that sibling is left to the reader.

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?

Annotations already flag destructiveHint=true; the description adds the actual effect ('hiding every other loaded model') and the recovery path via viewer_clear, which the annotation alone doesn't convey. It doesn't mention whether the hide is scoped to the session or persisted, so it falls just short of 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?

Three sentences, front-loaded with the effect, then the cost/alternative rationale, then sourcing and undo. No filler and nothing buried.

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 no explanation; the description covers the effect, argument sourcing, alternative selection, and reversal. Nothing an agent needs to call this correctly is missing.

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 carry the parameter meaning, and it does: exact-name matching, a concrete example ('Snowdon Towers Sample HVAC'), and the authoritative source for names (viewer_get_state's 'models' list). It stops short of stating array/multi-value behavior or what happens on an unmatched name.

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 and resource ('shows only the given model(s)/discipline(s)... hiding every other loaded model') and names the siblings it differs from (viewer_isolate, viewer_clear, viewer_get_state). An agent can distinguish this from viewer_isolate without opening either schema.

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?

Explicitly says when to prefer this over viewer_isolate ('cheaper... no need to resolve every element's pnt_id first'), where to source the required names (viewer_get_state's 'models' list), and how to reverse it (viewer_clear). When, why, and alternatives are all present.

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?

Annotations declare readOnlyHint=true; description adds context that it reads a specific file (clashes.json) rather than viewer data. No contradictions. Clarifies the non-destructive nature and data source.

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 concise sentences covering purpose, data source, and key output. No extraneous content.

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?

Given zero parameters, presence of output schema, and simple read-only operation, the description provides sufficient context. It mentions the critical return element (pnt_id identifiers) that aids tool selection.

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?

No parameters (schema coverage 100%). Description adds meaning by specifying that the return includes pnt_id identifiers for highlighting, which is useful beyond the empty schema.

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?

Clearly states it reads clashes.json (data source) and returns clash data with pnt_id identifiers for highlighting. Distinguishes from viewer/IFC and sibling tools like viewer_highlight_clash.

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?

Explains the tool's input (loaded package's clashes.json) and output (pnt_id identifiers). Implicitly contrasts with viewer/IFC and highlighting tool, but does not explicitly state when not to use alternatives.

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?

Annotations already indicate destructive hint, so description should elaborate on side effects. It mentions loading but does not clarify if previous viewer state is cleared, overwritten, or merged. The return of a summary is noted but not the behavioral impact on viewer 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?

Single sentence, efficient, front-loaded with action and result. No unnecessary words.

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?

Given the destructive hint and a single parameter, the description lacks completeness. It does not state if viewer must be empty, if loading fails gracefully, or how the summary is used. Output schema is present but not described.

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 description must add meaning. It mentions 'pnt_path' implicitly but provides no details on file format, required permissions, or format constraints. The parameter is not explained beyond its name.

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 clearly states the action ('loads'), the resource ('.pnt file'), the destination ('open viewer'), and the return value ('summary from clashes.json'). It is specific and distinguishes from sibling tools like viewer_clear or viewer_highlight_clash.

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 guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., viewer must be open) or typical workflow (e.g., use after viewer_list_clashes).

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?

Annotations only give destructiveHint=true, so the description must carry the real behavioural burden — and it does, disclosing that selection uses neutral yellow/blue colours, hides nothing else, and REPLACES any previous selection (which explains the destructive hint). What it doesn't cover is whether the selection persists across reloads or what the call returns, so it stops short of 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?

Front-loaded with the core action and its visual effect, then parameter usage, then alternatives. Every sentence carries information; there is no filler or restatement of the name.

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?

With an output schema present, return values need not be described, and the description covers purpose, both parameters, side effects (replacement), and sibling routing. Nothing an agent needs to invoke it correctly is missing.

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% (bare array-of-string titles), so the description must compensate, and it does: pnt_ids is 'group A' and pnt_ids_b is an optional second group highlighted in a distinct colour. The only gap is that it never states the pnt_id string format or whether the call errors on unknown ids.

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 (highlights) plus resource (a set of elements in the open viewer) and the scope ('by pnt_id, in neutral colours... with nothing else hidden'). It explicitly distinguishes itself from viewer_highlight_clash, which is named as a sibling for a different effect.

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?

Names the concrete alternatives and the conditions that select them: viewer_list_clashes / viewer_get_properties to obtain pnt_ids, and viewer_highlight_clash for a clash pair with the model isolated. A caller knows both when to use this tool and when to route elsewhere.

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?

Annotations already declare readOnlyHint=true, so the description adds value by specifying the reported status info. No contradictions exist, but the description does not elaborate on other behavioral traits like authentication or permissions.

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, well-structured sentence that conveys the core purpose and output immediately. No unnecessary words.

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?

Given the absence of parameters, the presence of readOnlyHint annotation, and an output schema, the description sufficiently explains what the tool does. It lacks only minor context like error conditions or response format, but the output schema covers that.

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 has zero parameters, so the description does not need to explain parameter semantics. The baseline score of 4 is appropriate.

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 clearly states the tool's purpose: reports whether a PyNet BIM Viewer is open in VS Code, and specifies the details it provides (port, package, data dir). While it differentiates from siblings by focusing on the viewer status, it does not explicitly exclude other status-checking tools.

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 provides no guidance on when to use this tool versus alternatives such as check_plugin_status or list_active_instances. Agents must rely on the tool name and context to infer usage.

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