Server Quality Checklist

Tool Scores

• sim_controlB
  3.1/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the behavioral disclosure burden. It usefully discloses reset semantics ('reloads the current circuit, zeroing time and all state'), but does not explain side effects of run/stop, whether operations block, or what status returns.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, front-loaded sentence that conveys the primary actions efficiently. The parenthetical detail about external voltage elements is somewhat dense but adds necessary precision without redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description omits the 'status' action entirely even though it appears in the schema enum. It also provides no return-value information, no constraints on combining parameters, and no mention of prerequisites, which is significant for a control tool with no output schema and no annotations.

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

  Parameters3/5

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

  Schema description coverage is low at 33%, and the description partially compensates by explaining extVoltage as an external voltage source element addressed by name. However, the action enum values have no accompanying behavioral descriptions, and maxTimeStep relies on the schema's unit example.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly identifies the tool's purpose: starting, stopping, resetting the simulation, setting max timestep, and setting external voltage source values. It uses specific verbs and a named resource, though it does not explicitly differentiate itself from siblings like run_transient.

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

  Usage Guidelines2/5

  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 such as run_transient. The action enum implies some usage, but there are no stated conditions, exclusions, or selection criteria.

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

• circuit_exportB
  3.4/5.0
  Behavior3/5

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

  With no annotations, the description must carry the behavioral context. It clearly indicates the tool produces either Falstad text or SVG, but it does not disclose whether the export returns content directly, creates a file, or has any side effects. Some useful behavior is stated, but meaningful context is missing.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, well-structured sentence that conveys the tool's purpose and its two output formats without redundancy. Every word contributes meaning.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool is simple, with one optional parameter, so extensive documentation is not required. However, since there is no output schema, the description does not clarify what the tool returns or how the exported content is delivered, leaving some ambiguity for an agent.

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

  Parameters4/5

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

  While the schema already documents the 'format' enum and default, the description enriches the enum values by explaining that 'text' means Falstad text format and 'svg' means a drawing of the schematic. This adds value beyond the bare parameter name and enum list.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description names a specific verb ('Export'), the resource ('the current circuit'), and two concrete output formats ('Falstad text format' or 'SVG drawing'). It is clear and informative, though it does not explicitly distinguish itself from sibling tools like screenshot or circuit_link.

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

  Usage Guidelines2/5

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

  There is no guidance about when to choose this tool over alternatives such as screenshot or circuit_link. The description states what it does but not in what situations it is preferred, nor what it is not for.

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

• screenshotA
  4.1/5.0
  Behavior4/5

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

  With no annotations, the description carries the full behavioral disclosure burden. It states that the tool returns a PNG image, optionally saves it to save_path, and includes scope traces only when scopes are defined. It does not mention file-overwrite behavior, but the core side effects are transparent.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single front-loaded sentence that conveys the primary action, the return value, the inclusion condition, and the optional parameter without redundancy. Every clause contributes useful information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple one-optional-parameter capture tool with no output schema, the description fully explains what is returned and the only optional side effect. An agent has enough information to invoke the tool correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the description only restates what the schema already says about save_path ('optionally also saves it to save_path'). No additional parameter meaning is added beyond the schema's explicit 'Absolute file path to also save the PNG to.'

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  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 ('Take a PNG screenshot of the circuit as currently drawn') and clarifies the included content ('including scope traces if the circuit defines scopes'). This clearly distinguishes the tool from siblings like circuit_export and circuit_load.

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

  Usage Guidelines3/5

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

  The description implies use for capturing the current visual circuit state and notes when scope traces are included, but it never explicitly states when to use this tool versus alternatives such as circuit_export. Usage context is present only by implication.

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

• circuit_stateA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full behavioral burden. It clearly frames the operation as a non-mutating read and lists what will be reported. It does not disclose potential edge cases such as behavior when the simulation is not running or the possibility of very large output, but it is generally transparent for a read-only state inspection tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is three sentences, each serving a distinct purpose: stating the primary behavior, linking to run_transient usage, and explaining the optional parameter. There is no redundancy or filler, and the most important information is front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple read tool with one optional parameter, the description covers the returned data, the source of valid node labels, and a cross-tool usage hint. Minor gaps such as output formatting, units, or error behavior are absent, but these are not critical for correctly invoking this tool.

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

  Parameters4/5

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

  The input schema has 100% description coverage, providing a baseline of 3. The description adds value beyond the schema by explaining that acceptable node names are labeled nodes and giving a concrete provenance example ('207 ...' labeled-node elements). It also clarifies the optional nature of the parameter.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a clear read operation on the current simulation state and enumerates the specific data returned: time, running flag, timestep, and per-element voltage difference, current, post voltages, and info string. The verb 'read' and the explicit data inventory distinguish it from the write/control siblings in the context.

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

  Usage Guidelines3/5

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

  The description provides a concrete usage hint: use returned element index values with run_transient probes. It also explains when to pass labeled node names. However, it does not explicitly state when to prefer circuit_state over siblings like circuit_load or sim_control, nor does it give any when-not-to-use guidance.

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

• run_transientA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description must carry the behavioral burden, and it does: it explains that simulation stops after the target time, returns partial data if wallTimeoutMs is hit, and that wall-clock can differ from simulated time. It does not explicitly describe side effects on circuit state beyond what fromReset implies, but the disclosure is still substantial.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is tightly structured: first sentence states the core operation, second defines the output and probe syntax, third explains timing behavior. Every sentence earns its place, and the key scoping constraint (SIMULATED time) is front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with five parameters, no annotations, and no output schema, the description is largely complete: it covers probe semantics, return shape, timeout behavior, and the sim-speed relationship. It could add a bit more detail about the exact output format or default reset behavior, but these are at least hinted at or covered by the schema.

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

  Parameters4/5

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

  Schema coverage is 80%, so some parameter meaning is already provided. The description adds real value by defining probe syntax and semantics: node probes read labeled voltage, element probes read current/voltageDiff/power with indices from circuit_state/circuit_load. This goes beyond the bare schema and compensates for the harder-to-infer parameters.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific action ('Run the simulation'), the resource (a transient simulation), and the core distinguishing scope (simulated time with probe sampling). It also identifies the return type as time-series data, so it is clear how this tool differs from siblings like circuit_load or circuit_state.

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

  Usage Guidelines3/5

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

  The description gives useful context, including how probe indices relate to circuit_state/circuit_load and how sim-speed affects wall-clock time. However, it never explicitly states when to prefer this tool over an alternative or what would be a better tool for a different task, such as sim_control.

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

• circuit_linkA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral burden. It discloses that the link opens in any normal browser with no install needed, uses the current circuit by default, and is intended for interactive viewing/editing. It doesn't mention potential sharing caveats or response shape, but for a simple read-only link generator it is reasonably transparent.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact and front-loaded. Three sentences each contribute: what it returns, how the input affects behavior, and how to use the result. There is no filler or duplication of schema details.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a low-complexity tool with no output schema, the description is complete. It identifies the output as a URL, explains the default behavior, names the destination simulator, and tells the agent what to do with the result. Nothing essential is missing for correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description reinforces the meaning of the `text` parameter by stating it overrides the current circuit, but it adds little beyond what the schema already says. `base` is not mentioned in prose, though its schema description covers it.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: returning a URL that opens the circuit in the Falstad simulator. It specifies the resource, the requested action, and the practical use case (view/edit interactively in Chrome), which distinguishes it from sibling tools like circuit_export or screenshot.

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

  Usage Guidelines4/5

  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: 'Give this link to the user so they can view/edit the circuit interactively in Chrome.' It also explains the key input behavior (uses current circuit unless text is given). It stops short of explicitly naming alternatives or saying when not to use it, so it isn't a full 5.

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

• circuit_loadA
  4.3/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses key side effects: replacing the current circuit, resetting simulation time to 0, keeping simulator state across calls, and returning parsed elements for verification. This goes beyond the bare schema and gives the agent useful behavioral expectations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three purposeful sentences cover action, input format, side effects, return value, and state persistence. The core operation is front-loaded, and there is no filler or repetition.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a moderately simple load tool with no output schema, the description covers the required input format, reset behavior, return value, and cross-call statefulness. Combined with a fully described schema, an agent has enough to call it correctly and interpret the result.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the schema already explains the text format, the '$' line, reasonable defaults, and the run boolean. The tool description adds no parameter-specific meaning beyond noting the returned element list, 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.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  States the operation (replace), the exact resource (current circuit), the input format (Falstad CircuitJS1 text starting with a '$' line), and the return value. This stands apart from siblings such as circuit_export and circuit_state, so an agent can select it correctly.

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

  Usage Guidelines4/5

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

  Clear that this tool is for installing a new circuit definition and that simulator state persists across calls, implying use at circuit-setup/load time. It does not explicitly name alternatives or say when not to use it, but no sibling has an overlapping function, so the gap is small.

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

• eval_jsA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It clearly explains the execution model: code becomes an async function body, receives the `sim` object, and must return a JSON-serializable value. It does not spell out side effects or error behavior, but the phrase 'run arbitrary JavaScript' strongly implies mutating potential.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences plus one example carry high information density with no filler. The core operational facts are front-loaded, and the example earns its place by clarifying the expected code shape.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description covers how to invoke the tool, what the code receives, the return contract, and links to the simulator's documented interface. It lacks explicit caveats about side effects or serialization failures, but given the tool's arbitrary-code nature and the provided example, an agent has enough to call it correctly.

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

  Parameters5/5

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

  The single `code` parameter is fully elaborated despite 0% schema description coverage. The description defines what the code should look like, what context it receives, what it must return, and provides a practical example. This fully compensates for the schema's minimal parameter definition.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description names a specific verb and resource: run arbitrary JavaScript inside the CircuitJS1 page. The 'advanced escape hatch' framing and concrete example clearly distinguish it from the sibling tools, which are more specialized operations.

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

  Usage Guidelines3/5

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

  Usage context is only implied by 'Advanced escape hatch,' suggesting it is a fallback when the standard tools cannot express the needed operation. It does not explicitly state when not to use it or name any sibling alternatives for common cases.

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