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

Annotations already declare readOnlyHint and idempotentHint, so the tool is known to be safe. The description adds the behavioral directive to call it first, providing context beyond structured annotations. 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?

Two sentences with no wasted words, front-loaded with purpose and immediately providing actionable usage guidance.

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 available and zero parameters, the description fully covers the tool's purpose and usage, making it complete for an agent to select and invoke 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?

The tool has zero parameters, so the description has no parameter semantics to cover. The baseline of 4 applies as there is nothing to clarify.

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 a specific action ('Discover') and resource ('available API guidance and skills'), distinguishing it from sibling tools like read_skills (which loads guidance) and list_instances (which lists instances).

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 instructs 'Call this FIRST before using other openstaad-mcp tools' and directs to 'read_skills' for loading full guidance, providing clear when-to-use and an alternative.

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 destructiveHint=true, readOnlyHint=false, openWorldHint=false, idempotentHint=false, so the safety profile is covered. The description adds substantial value beyond annotations: import/dir()/getattr() are BLOCKED, pre-injected variables (staad, input_data, json, math), result return semantics, overwrite behavior via output_data_path, and path locality constraints. It doesn't connect to the annotations directly.

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?

Very long and dense, especially the output_data_path rules which read like a formatting spec rather than tool guidance. Front-loads the core purpose well but the units/header/sheet rules are excessively verbose for a description field and would be better in a docs resource. Every sentence is useful but the size is disproportionate.

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 execution environment constraints, injected variables, results handling, output writing, and path locality. Output schema exists, so return shape explanation is optional. Missing: explicit statement that this is destructive (surfaced only via annotations), and what 'against' the API means in practice (does it need a connected instance?).

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 100%, so all five parameters are documented in the schema. The description mentions input_data/output_data_path behavior at a high level but the deep formatting rules (units, header rules, result shapes) are duplicated in the schema descriptions. Baseline 3 is appropriate since the schema does the heavy lifting.

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?

Strong verb+resource ('Execute Python code in a sandbox against the OpenSTAAD API'), specific target identified. Not differentiated from siblings in the description, but the sibling names (discover_api, read_skills) are referenced as prerequisites which implicitly distinguishes the role. Loses a point for lacking explicit sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to call discover_api and read_skills for API guidance before/while using this tool. It names the alternative tools to consult. However, it doesn't state when NOT to use this (e.g. versus a direct filesystem or other execution path) and doesn't define conditions or sequencing beyond the reminder.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds genuinely new behavioral context: that the MCP server must be relaunched for allowed-directory changes to take effect, so a cached allowed_dirs list can silently look correct and must be refreshed by calling this tool again.

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 purpose, then parameter guidance, then return/refresh caveats — good ordering. The final sentence about the relaunch requirement is long but earns its place by preventing a stale-read mistake; slightly verbose but not wasteful.

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, the description need not enumerate return values, yet it still highlights the key fields (connection state, STAAD version, model path, allowed_dirs) and the refresh caveat. Given one optional param and full annotation coverage, 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 description coverage is 0%, so the description carries the burden for the single optional parameter. It fully explains it: it is an alias obtained from list_instances, used to target a specific instance, and should be omitted when only one instance is running — more than the schema's bare anyOf/null/default conveys.

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 ('Check the connection to a STAAD.Pro instance') and clearly differentiates itself from siblings like list_instances and execute_code. An agent can tell at a glance this is a status/diagnostic call rather than a discovery or execution call.

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 describes when to pass the instance alias vs. omit it ('Omit it when only one instance is running') and when to re-call ('after the user reconfigures allowed directories'). It references list_instances as the source of the alias, though it does not frame an explicit 'use X instead of this' alternative.

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, but the description adds valuable behavioral context: the alias is stable across model file changes, and a warning field appears for versions below 25.0.1. These details go beyond what annotations provide and help the agent anticipate edge cases.

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 concise, front-loaded with the core purpose, and uses a short second paragraph for usage and conditional behavior. Every sentence contributes useful information, making it appropriately sized and well-structured.

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's simplicity (0 params), rich output schema, and strong annotations, the description covers the essential aspects: what it lists, when to use it, and a notable behavior (version warning). No important gaps are evident.

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 input schema is empty. The baseline for 0 params is 4. The description reinforces 'all instances' and the return fields, but since there are no parameters to explain, it cannot add more parameter-specific meaning.

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 opens with a specific verb and resource: 'List all running STAAD.Pro instances.' It clearly states the tool's function and distinguishes it from siblings by mentioning the returned fields (alias, process ID, file path, version) and its role as a precursor to execute_code.

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 explicitly says 'Call this before execute_code when multiple STAAD instances may be running so you can pick the right one.' This gives a clear when-to-use directive and a rationale, which is more than the minimal context needed for a simple listing tool.

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 idempotentHint=true, so the description doesn't need to restate safety. It adds useful behavior context by mentioning sub-paths like 'staad-steel-design/assets/DESIGN_CODES' to read reference files, and explains skills provide domain-specific guidance.

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 compact and front-loaded: the first sentence states the primary purpose, followed by prerequisite guidance and examples. No redundant or filler 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?

For a simple read tool with a single parameter and an output schema, the description fully covers how to use it: what it reads, how to discover available skills, and how to pass names or sub-paths. The output schema handles return values, so no additional explanation is needed.

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 schema covers 100% of the parameter description, but the description adds concrete examples ('["staad-analysis"]' and sub-paths) and clarifies that sub-paths read reference files within a skill. This goes beyond the schema's generic 'List of skill names or sub-paths'.

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 reads one or more skills by name, with the verb 'read' and resource 'skills'. It also distinguishes from sibling tools like discover_api (lists skills) by describing the sub-path capability for reading reference files.

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 explicitly instructs to 'Use discover_api first to list available skills', providing a clear prerequisite and context. It doesn't explicitly state when not to use this tool, but the read-only nature and examples suggest it is for accessing skill content, not for executing commands.

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