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

Annotations already indicate readOnlyHint=false, so a mutation is expected; the description does not contradict this. It adds useful behavioral context beyond the annotations by stating that the tool returns resolved parameters, inputs, states with units, port paths, and pre-flight issues including unconnected ports until connected. This helps the agent understand side effects and follow-up 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?

The description is extremely concise: one purpose sentence followed by one return-value sentence. Every sentence earns its place, and the primary action is front-loaded. There is no filler, redundancy, or schema repetition.

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 output schema and annotations, the description covers the essential purpose and return behavior well. It also highlights a meaningful behavioral detail about pre-flight port issues. It falls short only in not providing usage guidance or alternative routing, but nothing critical is missing for a competent agent to invoke 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?

Schema description coverage is 80%, so the schema already documents four of five parameters clearly. The description itself adds little parameter-level meaning, only referencing 'resolved parameters' in the return value. system_id is the only undocumented parameter, but its purpose is obvious from its name and the sibling 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 opens with a specific verb and resource: 'Add a component instance to a system.' This clearly distinguishes it from sibling tools like describe_component, list_components, and remove_component. The additional return-value sentence reinforces what the tool accomplishes without muddying its purpose.

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 is given about when to use this tool versus alternatives such as create_system, describe_component, or set_values. The context is implied only by the verb 'add,' leaving the agent to infer that this is the right tool for inserting a component instance into an existing system. There are no exclusions, prerequisites, or alternative-selection hints.

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 goes beyond the annotations by explaining execution behavior: pi runs during solve and simulate, 'control_saturated' appears when unreachable, and hysteresis has threshold and short-cycling behavior. This adds meaningful context without contradicting the readOnly/openWorld/destructive hints.

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 with the core purpose, then uses efficient colon-separated type breakdowns. It is dense but not bloated, though the pi/hysteresis details could be slightly better organized.

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 output schema exists and annotations cover safety, the description covers the main behavioral aspects and return value ('Returns every control'). It lacks explicit side-effect or error information, but for a 6-parameter tool with nested settings, it is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is high (83%), but the description adds valuable parameter semantics, especially for the settings object: it explains pi setpoint/gain/integral_time and hysteresis on_below/off_above behavior. This goes beyond the raw schema definitions.

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: 'Add a control that reads one result and writes one component input.' This clearly distinguishes it from adding components or removing controls, though it does not explicitly name sibling tools for 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?

The description provides detailed guidance for the two control types (pi and hysteresis) but does not explain when to choose add_control over alternatives like set_values, connect, or add_component. No when-to-use or when-not-to-use conditions 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?

The description adds substantial behavioral context beyond the readOnlyHint annotation: it lists stable issue codes, marks unconnected_port as a warning, distinguishes error categories for controls, and states that solve/simulate will refuse to run while errors remain. This gives an agent a clear mental model of what the tool returns and how it interacts with downstream operations.

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 with the core purpose. The issue-code list is dense but relevant, and the solve/simulate refusal behavior is placed last as a natural consequence. Every sentence contributes meaningful information without repetition or filler.

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 single-parameter read-only validation tool with an output schema, the description is nearly complete. It explains the validation scope, the warning/error semantics, and the relationship to solve/simulate. It does not spell out the exact return format, but that is covered by the output schema, so this is not a significant gap.

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 only lists system_id as a required string with zero description coverage. The description does not add parameter-specific guidance, so the agent must rely on the parameter name. 'system_id' is reasonably self-explanatory in context, but the description does not compensate for the schema's lack of detail, leaving a minor 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 opens with 'Structural pre-flight', which clearly identifies the tool as a validation/checking operation on a system. It goes beyond the tool name by explaining that it produces stable issue codes. It distinguishes itself from retrieval siblings like get_system and list_components by focusing on structural validation, and from solve/simulate by being the pre-flight that blocks them when errors remain.

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 last sentence says that solve and simulate refuse to run while any error remains, implying the correct usage is to run check_system before attempting solve or simulate. This gives a clear contextual trigger without being an explicit 'use this when...' statement. It does not name alternative validation tools or state when not to use it, so it stops short of a 5.

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 safety profile is covered. The description adds useful behavioral context by revealing that the tool executes an external simulation with WNTR/EPANET, compares specific quantities, and reports divergence reasons. It does not contradict annotations and goes beyond the bare mutation/read distinction.

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, information-dense sentence that front-loads the action and includes units and comparison criteria. Every phrase earns its place, with no filler or repetition.

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 description states what will be computed, the units, and the comparison intent, while the presence of an output schema covers return-value shape. It does not mention external dependencies like WNTR availability or potential runtime behavior, but for a single-parameter read-only comparison tool this is a minor gap rather than a blocker.

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 for parameter semantics. It only refers to 'the system' and does not explain what system_id should be, how to obtain it, or any format constraints. The parameter name is self-explanatory to a degree, but the description adds essentially no meaning beyond the 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?

The description uses a specific verb (solve and compare), names the target resource (the system), and specifies the expected outputs (per-link flows in m3/h, node pressures in bar gauge, plus the differences and why they diverge). This clearly differentiates it from sibling tools like solve and simulate by adding the EPANET/WNTR comparison dimension.

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 clearly states the context: use this tool when you need to solve the system and compare results against EPANET via WNTR. It does not explicitly name alternatives or exclusion conditions, but the purpose is specific enough that an agent can infer when it is the right choice versus solve or simulate.

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 goes well beyond the minimal annotations, explaining error behavior (naming offending port, listing valid ports), return payload (connections and unconnected ports, capped), and the junction/tee behavior. This fully compensates for the sparse annotations and gives the agent a clear model of side effects.

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 verb, then compactly adding behavior, error, and return info. No filler or repetition.

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 three-parameter mutation tool with an output schema and sparse annotations, the description covers the action, behavioral consequences, errors, and return format. It omits a comparison to sibling tools and doesn't explain system_id, but otherwise gives an agent enough to invoke and interpret the result.

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 already describes 'a' and 'b' with examples; the description adds no new parameter-level meaning. It fails to explain 'system_id', and with 67% schema coverage the description does not compensate for that 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 clearly states the tool connects two ports and adds a useful behavioral detail about forming a tee junction, but it does not explicitly distinguish it from the sibling 'disconnect' or other graph-mutation 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?

There is no guidance on when to use this tool vs alternatives, no mention of 'disconnect' or conditions under which connecting is appropriate. The description is entirely about the action itself, not selection criteria.

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 this as not read-only and not destructive, so the description only needs to add context; it does add that the system is empty and that system_id is returned. However, it does not disclose side effects, idempotency, or requirements beyond the schema. No contradiction with annotations.

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 first sentence is concise and front-loaded, but the second sentence is syntactically awkward and unclear, which undermines the message. It is short, but not 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 a 2-parameter schema, output schema, and safety annotations, the core is covered, but the ambiguous relationship to load_system leaves a real gap: an agent cannot confidently decide between create_system and load_system. This prevents a higher score.

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 covers both parameters (name and description) with descriptions and defaults, so the baseline is 3. The tool description adds no parameter-level meaning beyond what the schema already provides.

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 first sentence uses a specific verb ('Create'), names the resource ('new empty system'), and states the return value ('system_id'), which clearly distinguishes it from read-oriented siblings. The second sentence is confusing but does not obscure the core purpose.

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 says 'For building step by step' and mentions load_system, implying a comparison, but it never explicitly states when to use create_system instead of load_system or other siblings. The phrase 'a new system is quicker as one load_system call' is grammatically ambiguous, leaving the routing rule unclear.

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?

Even though readOnlyHint=true is already in annotations, the description adds substantial behavioral detail: batch ordering with {components: [...]}, the meaning of state 'steady' values, warning source semantics, and unit conventions for pressures and temperature_difference. This goes well beyond what annotations provide.

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 dense but every sentence carries useful information: purpose, batching behavior, returned content, units, and special semantics. It is front-loaded with the main purpose. A bulleted layout might improve readability, but there is no redundancy or filler.

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 complex introspection tool, the description covers the essential ground: what the output contains, ordering guarantees, unit conventions, state semantics, and warning semantics. Combined with the output schema and readOnly annotation, an agent has enough information to call and interpret 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?

The input schema already documents both parameters thoroughly, including enums, defaults, maxItems, and examples; schema coverage is 100%. The description reinforces batching with 'as a list in one call' and output ordering, but it does not add significant new semantic meaning to the parameters themselves.

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: 'Describe component types: everything needed to use them.' It clearly differentiates itself from siblings like list_components (which would just enumerate components) and get_system (which targets a whole system), making the tool's 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 gives clear context for when to use the tool: whenever you need details required to use components. It also provides a concrete usage pattern: 'Pass every component you need as a list in one call.' It does not explicitly name alternatives or exclusions, but the intended context is clear.

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 and readOnlyHint=false, and the description's 'Remove' aligns with that. The qualifier 'direct' adds a small behavioral note implying only direct connections are affected, but it omits side effects or error behavior. Given annotation coverage, this is adequate but not rich.

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 conveys the core action and object 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?

An output schema exists, so return values are covered. However, the description lacks usage context and system_id semantics, and the only hint about indirect connections is a single adjective. For a three-parameter destructive tool, this is minimally viable but leaves gaps.

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 already describes a and b as 'Port path' with 67% coverage. The description confirms these are the two ports but adds no meaning for system_id, which is undocumented in both schema and description. It 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?

The description uses a specific verb and resource: 'Remove the direct connection between two ports.' This clearly identifies the tool's action and object. It is distinct enough from siblings like connect and remove_control, though it doesn't explicitly name them for 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?

No guidance is provided on when to use this tool versus alternatives. The description does not mention, for example, that this tool is for direct port connections and not for controls, nor does it reference the connect sibling as the inverse operation.

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 and openWorldHint=false, so the description is consistent. It adds context about unsupported elements (faucets, heaters) and notes that the export approximates, which is valuable beyond the annotations. No contradiction.

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—two short sentences. The purpose is front-loaded, and the limitation notes are placed efficiently. No unnecessary words or repetition.

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 description covers the core purpose and key limitations, and an output schema exists. However, it lacks guidance on when to use the tool versus siblings and does not mention error handling or return format details. Given its simplicity, it is adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%: the target parameter has a description, but system_id has none. The tool description does not elaborate on parameters—it doesn't explain system_id format or provide usage details. Since coverage is below 50%, the description should compensate but doesn't.

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 function: 'Export a system as EPANET .inp text' with specific units and method (CMH, Darcy-Weisbach). This is a specific verb-resource pair that distinguishes it from sibling tools like get_system or list_components. The purpose is 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 provides some context (mentions unsupported faucets and heaters) but does not explicitly state when to use this tool over alternatives. It does not reference sibling tools or give conditions for selection. The 'notes' hint about approximation is useful but not a full usage guideline.

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, and the description adds context about what the returned document contains (components, connections, changed states, controls, optional simulation block) and its downstream role with load_system. It does not cover errors or missing IDs, but the output schema covers return structure.

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, front-loaded with the core meaning and followed by a useful workflow hint. No filler or repetition.

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 one-parameter read-only getter with an output schema, the description covers document contents and workflow adequately. The main gap is the undefined system_id parameter, which prevents full end-to-end understanding of how to call 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?

The schema provides only an untyped system_id with no description, and the description never mentions this parameter. With 0% schema coverage and no compensating text, the agent must infer the meaning of system_id from the tool name and description alone.

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 names the resource (system document, design 6.3) and lists its contents, making clear that this tool retrieves the full system document. It does not explicitly differentiate from siblings like export_system or describe_component, but the combination of name and description is sufficiently specific.

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 instruction 'Pass it to load_system later' provides a concrete workflow context and indicates when this tool is useful. It does not mention when not to use it or list alternatives, but it gives clear enough context for deciding.

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 and openWorldHint=false, so the safety profile is covered. The description adds the return field list and the workflow with describe_component, but no additional behavioral traits such as pagination or ordering. Given the annotations, this is adequate but not rich.

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 carry all the essential information: the search purpose, the exact return fields, and the usage workflow. No redundancy or filler; the most important detail (what it returns) comes first.

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-only listing tool with an optional query parameter and an output schema, the description is complete enough. It explains how to invoke it (with or without query) and how it connects to describe_component. Minor gaps like pagination are not critical given the output schema and annotations.

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 100% and the single parameter query is fully documented in the schema. The description adds no extra semantics beyond what the schema already states, so the baseline score of 3 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?

The description clearly states the tool searches the component catalogue and enumerates the returned fields (id, alias, name, summary, ports, key parameters, fidelity, tags). It also distinguishes itself from describe_component by framing it as the list/search step followed by describe_component for details, so an agent can tell them apart.

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 gives an explicit workflow: call without a query to list everything, then use describe_component for the components you need. That tells the agent when to use this tool versus its sibling. It could go further by stating when not to use it (e.g., when you already know a component ID and need full details), but the implied guidance is strong.

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 it readOnly and closed-world; the description adds useful behavior beyond those: enumerates output kinds, flags state as settable, and documents port naming/units and control variable conventions. It does not mention pagination or result size, but 'Every variable path' signals exhaustiveness.

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 exactly what is returned, and the second condenses a taxonomy of variable kinds into a few lines. No filler or repetition of the schema.

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 read-only annotation, an output schema, and only two parameters, the description carries enough domain context to call the tool correctly. The main residual gap is clarifying what system_id refers to, but sibling naming and the required field make that reasonably inferable.

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?

system_id is undocumented in the schema and not explained in the description, leaving a gap at 50% coverage. However, the description does add semantic value for the component parameter by defining the special 'control' value and the port path patterns that filter results.

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 identifies the resource and output: 'Every variable path with kind, unit, limits and description.' It is clearly about variables rather than components or systems, which separates it from list_components and get_system, though it lacks an explicit imperative verb.

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 given about when to choose this tool over list_components, describe_component, or other siblings. The only conditional guidance ('component='control' lists them') is an internal parameter detail, not 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?

With annotations limited to three false hints (readOnly=false, openWorld=false, destructive=false), the description carries the behavioral burden and delivers: it discloses failure mode ('A wrong shape fails with every schema error and the expected shape of the offending part'), the issues mechanism ('unknown types, ports and invalid values are kept and listed in issues'), the equivalence to check_system, and the 'fix every error, then solve' workflow. This is substantive context well beyond the annotations, and nothing contradicts them.

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 main action and return value are front-loaded in the first sentence, followed by a tight paragraph on use case and failure behavior. Every sentence carries information (document source, error handling, issue reporting, next step), with no filler or repetition of the schema's example.

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 output schema exists (so return format is covered elsewhere), the description is complete for a complex one-call system builder: it explains the document source, validation and error behavior, the issues report link, and the follow-up solve step. The only minor omissions (auth/overwrite semantics) are not required given the annotations and schema richness.

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% with a rich example, so the baseline is 3; the description earns a 4 by adding validation semantics for the document parameter: what happens on malformed shape, that unknown types/ports/invalid values are preserved in `issues`, and that get_system returns a conforming document. This goes beyond the schema's structural description.

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 opening sentence states a specific verb and resource: 'Build a whole system in one call from a system document; returns its system_id.' The phrase 'whole system in one call' clearly distinguishes this from the incremental siblings (add_component, connect, add_control) and from create_system, so an agent can tell them apart without opening schemas.

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 gives clear context for when to use it ('The quickest way to create a system... every component, connection and control in one document, then solve') and names get_system as the source of a valid document. However, it does not explicitly name alternatives or state when-not-to-use it (e.g., modifying an existing system via add_component/connect), so it falls short of fully explicit routing.

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 this as destructive (destructiveHint=true), so the description's added value is specifying what gets destroyed: the component instance and all its connections. This cascading behavior is a useful behavioral disclosure beyond the annotation and is consistent with readOnlyHint=false.

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 that states the verb first and packs the key behavioral scope ('and every connection to it') into a compact phrase. 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?

For a simple destructive operation with an output schema and annotations, the description covers the essential behavior and cascade scope. The main gap is the undocumented 'system_id' parameter, but overall an agent has enough context to invoke 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?

Schema coverage is only 50%: 'name' is described as 'Instance name to remove', but 'system_id' has no schema description. The tool description does not clarify 'system_id' or add meaningful parameter semantics beyond what the schema already says about '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 names a specific action ('Remove'), a specific resource ('component instance'), and a clear scope ('every connection to it'), which distinguishes it from sibling tools like disconnect or add_component. It is not a tautology and an agent can tell what it does without opening the 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?

The description implies usage for deleting a component instance, and the phrase 'every connection to it' hints that this is not the tool for merely disconnecting a component. However, it never explicitly says when to choose this over disconnect or other siblings, nor does it state 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?

Annotations already indicate destructiveHint=true, so the description doesn't need to signal that removal is destructive. It adds useful non-obvious behavior: the control's input retains its last value after removal. This goes beyond the annotation and clarifies a meaningful side effect.

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. Every phrase earns its place: the action is stated first, and the side-effect clause adds one genuinely useful detail.

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 two-parameter destructive tool, the description plus annotations and output schema provide enough to select and invoke the tool correctly. It clearly names the target resource and a key side effect, though it could strengthen sibling differentiation with explicit when-to-use guidance.

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 describes 'name' as the control name but leaves 'system_id' undocumented, giving 50% coverage. The description does not explicitly explain either parameter, but the term 'control' reinforces the role of 'name'. The two-parameter schema is simple enough that the agent can largely infer semantics, though not fully.

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 action and object directly: 'Remove a control'. It also adds a concrete behavioral detail ('its input keeps its last value') that clarifies the exact scope of removal and distinguishes it from sibling tools like remove_component.

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 guidance about when to use this tool versus alternatives such as remove_component or add_control. No prerequisites, exclusions, or decision context are provided, so the agent must infer usage 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 already declare readOnlyHint=trueтные; the description adds value by explaining what contracts check and that evaluation is against the reference implementation. It does not contradict annotations or mention side effects, which is acceptable given the read-only hint.

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 tightly scoped sentences: the first states the action and result, the second clarifies the underlying test categories. No filler or redundant restatement of the tool 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 one required parameter, full schema coverage, an output schema, and read-only annotations, the description supplies enough behavioral context to invoke the tool correctly. It could slightly improve by addressing when to prefer this over sibling checking tools, but that gap is not critical.

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 already provides 100% coverage for the single parameter with 'Full id or short alias.' The description adds no additional parameter-level detail, so it meets but does not exceed the baseline.

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 action ('run'), a clear resource ('a component's scenarios and contracts'), and a concrete outcome ('report pass or fail'). It further distinguishes itself from validation/checking siblings by detailing what contracts verify (monotonicity, bounds, conservation, warning conditions against the reference implementation).

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 for testing a component's scenarios and contracts)Skip. It doesn't explicitly state when to use this over siblings like check_system or compare_with_wntr, nor does it mention exclusions or 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?

The annotations provide only readOnlyHint=false, openWorldHint=false, and destructiveHint=false. The description adds valuable behavioral detail: writes are atomic ('all or nothing'), unit encoding rules are specified, and the tool returns the values now in effect. These traits are not captured by the annotations or 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 two tight sentences with no filler. It front-loads the verb and target resource, then packs atomicity, unit handling, and return semantics into a compact second sentence.

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 two-parameter mutation tool with an output schema and safety hints in annotations, the description is complete: it explains the operation, failure semantics, input encoding, and return behavior. The only small gap is explicit alternative-tool guidance, which is already handled by the clear purpose and sibling list.

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 adds meaningful semantics for the values parameter, explaining how plain numbers and unit-bearing strings are interpreted. The schema covers values with an example but leaves system_id undocumented; the description cannot fully compensate for that, though system_id is self-explanatory from 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 opens with a specific verb ('Set') and names the exact target resource ('inputs, parameters or states') plus the addressing mechanism ('by path'). This makes the tool's purpose concrete and distinguishes it from read-only or analysis siblings like get_system, list_variables, solve, and simulate. It is not a tautology and states atomicity as part of the operation.

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 clearly frames this as the mutation of existing values by path, which is distinct from creating components (create_system/add_component), connecting elements, or running simulations/solves. It does not explicitly list exclusions or when-not conditions, but the context is enough for an agent to separate it from the sibling tools.

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 indicate readOnlyHint=false (mutation allowed) and destructiveHint=false. The description adds critical context: it mentions the system keeps its final state unless restore is true, and details the exact output behavior (downsampled series, min/max/final, warnings once, mode changes, control series). This goes beyond annotations and fully discloses side effects and return semantics.

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 about 100 words and every sentence delivers essential information. It leads with the core purpose, then details sampling, output, and side effects. No redundancy or filler; each clause is necessary.

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 complexity of an 8-parameter simulation tool with events, controls, and state restoration, the description covers all essential behavioral aspects: sampling schedule, output contents, control semantics, side effects, and restoration option. The output schema exists (implied by 'returns downsampled series'), and the description aligns with it. No critical gaps.

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 88%, so most parameters already have descriptions. The description adds value by explaining behavioral semantics: 'Samples at every multiple of step, at each event time and at the end' clarifies how step and events are processed, and 'controls reports each loop at the end' explains the control output. This enriches understanding beyond the 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?

The description explicitly states the tool simulates over time with a fixed step and timed events, clearly distinguishing it from siblings like `solve` or `solve_for` which likely handle steady-state or targeted solves. The verb 'Simulate' plus resource 'over time' makes the purpose 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 clearly indicates this is for time-based simulation with step and events, which implies the use case. However, it does not explicitly name alternatives or state when not to use it, unlike the calibration example that specified 'To filter by user/workspace, use search_calls_extensive instead.' Still, the intent is clear enough for an agent to select it appropriately.

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?

Despite readOnlyHint=true, the description adds extensive behavioral detail: 6-significant-digit precision, pressure reference handling, port pressures in bar gauge, per-instance modes, component warnings and non-fatal issues, failure on check_system errors, and control loop behavior (PI setpoint holding, hysteresis state holding, and the `controls` report contents). This goes well beyond the annotations.

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 and well-structured: purpose sentence, return details, failure behavior, then control semantics. No sentence is wasted, and each clause contributes actionable information. Front-loading the core purpose makes it easy to parse.

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?

Together with the annotations (readOnlyHint) and the presence of an output schema, the description covers the key facts an agent needs: what the tool solves, what it returns, units and precision, failure condition, and control behavior. It omits only minor operational details such as convergence failure handling, which the output schema likely covers.

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 67% schema description coverage, the schema already documents `units` and `variables` reasonably. The description adds meaning by explaining how selections are returned ('selected values') and by specifying unit formatting (significant digits, pressure reference/gauge), which clarifies the `units` parameter's effect. It does not elaborate on `system_id`, but that parameter is self-evident.

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 — 'Solve the steady operating point' — and the output list (values, modes, warnings, errors) makes the scope concrete. This distinguishes it from siblings like simulate (transient) and solve_for (targeted solve) without needing to open their schemas.

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 simulate, solve_for, or check_system. The only contextual hint is 'Fails with the list of errors when check_system reports any', which describes failure behavior rather than recommending a workflow or specifying conditions for choosing this 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?

The description goes well beyond the annotations (readOnlyHint=false, destructiveHint=false): it discloses the algorithm, the on-failure post-condition ('error reports it at both bounds and nothing changes'), and the on-success state mutation ('vary stays at the value found; the result is the operating point there'). This tells an agent exactly what state changes and what happens on partial failure, consistent with the annotations.

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?

Four sentences across three paragraphs with no filler: purpose first, then mechanism with example, then failure behavior, then success post-condition. Every sentence carries distinct information, and the 'as from solve' comparison earns its place by relating the output to a known sibling.

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 8-parameter numerical inversion tool with state mutation, the description covers the algorithm, parameter roles, the bounds-bracketing requirement, the failure mode, and post-conditions. Since an output schema exists, return-value details are appropriately delegated rather than repeated. The optional parameters (units, variables) are left to the schema, which already documents them well.

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 88%, so the baseline is 3, and the description adds relational meaning the schema cannot express: vary is the sole adjusted variable bounded by lower/upper, and the loop runs until target equals value. The worked example ties vary ('pump speed') and value ('15 m3/h') to concrete entities. It delegates per-parameter details to the already-rich schema, which 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 opening sentence defines the tool's precise role—finding the input or parameter value that yields a target result—and names the numerical method (Brent's method) with a concrete example (pump speed for 15 m3/h). The 'as from solve' reference situates it against its nearest sibling, framing solve_for as the inverse of solve, so an agent can tell them apart without opening schemas.

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 goal-seeking context is stated clearly up front: adjust one input until a target equals a value. The failure clause also implies correct usage—bounds must bracket the target crossing, otherwise the error reports both bounds and nothing changes. However, it never explicitly names an alternative or a when-not-to-use condition; the 'as from solve' remark hints at the relationship but stops short of explicit routing.

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