Multimeter

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

Annotations already provide readOnlyHint=true, so safety is covered. The description adds useful context about the tool's lightweight nature and explicitly forbids running shell/scripts, which is a behavioral constraint not in 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 compact and front-loads the purpose before routing to siblings and constraints. Slightly dense but each sentence earns its place.

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

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

Given the tool's simplicity (2 params, output schema absent, read-only), the description covers what the tool does, when to use it, and what to avoid. It also names the next step, making it complete for an agent planning a test.

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 parameters are fully documented. The description does not add much detail about the two parameters beyond what's in the schema, but it does imply apiPath is the target and workspaceRoot is the context. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns a compact API summary (method, url, inputs, outputs, suggested paths) and explicitly contrasts with 'dumping the full file.' This distinguishes it from siblings like read_documentation and discover_api.

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?

It explicitly says to prefer this over reading the whole file when generating or planning a test, and names the next-step sibling (scaffold_test). It also lists disallowed commands/tools (testlight, npx, npm, shell, node), giving clear when/not-when guidance.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to restate safety. It adds useful behavioral context: selectedApi omits full file content unless includeContent=true, and lists forbidden execution pathways. It stops short of describing return format or error behavior, but the added context is meaningful.

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 dense sentences with no wasted words. The use case is front-loaded, alternatives are named, the behavioral caveat is stated, and the prohibition is isolated at the end. Every sentence earns its place.

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

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

For a read-only discovery tool, the description covers when to call it, which siblings to prefer, and a key output caveat. The main gap is that the return shape beyond selectedApi is not described, and there is no output schema to compensate, but the tool is simple enough that this is a minor omission.

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%, so the baseline is 3, but the description adds real value by explaining that selectedApi's content inclusion depends on includeContent. It also frames apiPath and workspaceRoot in the workflow context, helping the agent understand when each is relevant.

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 purpose: listing workspace APIs or inspecting one before scaffolding a test. It also differentiates itself from siblings by explicitly preferring api_card for a single API and scaffold_test for new tests.

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?

It gives explicit when-to-use guidance and names the preferred alternative for each adjacent case. The guardrail against using testlight, npx, npm, shell, or node dist/mcp/server.js adds concrete boundary information.

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 says 'Format a Multimeter file', which implies modifying the file's contents, while annotations declare readOnlyHint=true. This is a direct contradiction: the agent cannot tell whether the operation rewrites the file or only reads it. No additional behavior (output, error, side effects) is disclosed. Flagged as Annotation 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 short and front-loads the main purpose before usage and exclusion guidance. The last sentence about not using testlight/npx/npm/shell/node is unusual and slightly distracting, but the overall structure is efficient.

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

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

The description doesn't state whether the file is modified in place, what the output/return value is, or how canonical ordering is applied. With no output schema and a contradiction with the readOnlyHint annotation, an agent lacks enough information to predict the tool's behavior.

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

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

Schema description coverage is 100%, so the parameters file and workspaceRoot are already documented in the schema. The description adds only the general purpose of formatting, not parameter-specific meaning, which meets 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 uses a specific verb ('Format') and resource ('Multimeter file'/.mmt) and mentions canonical field ordering and style rules, which differentiates it from siblings like validate and run. The title reinforces the .mmt scope.

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?

It gives explicit timing guidance ('Call after validate passes') and the intended use case ('normalizing generated or edited YAML'). It doesn't explicitly name alternative tools for non-formatting needs, but the ordering constraint 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 readOnlyHint=true, and the description does not contradict that. It adds context about the tool's purpose (returning example structure) and provides guidance on when it should be invoked, but it does not elaborate on return format, pagination, or other behavioral nuances. The description adds modest value beyond the annotation.

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

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

The description is concise and front-loaded: the primary use case is stated first, followed by the exclusions. No wasted words, and every sentence contributes to agent understanding.

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

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

For a simple tool with no required parameters and no output schema, the description provides sufficient guidance on when to call it and what it returns (examples). It lacks detail on the output format, but that is not critical given the tool's simplicity and the read-only annotation.

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

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

The input schema has 100% coverage, with each parameter properly described. The description does not add extra detail beyond the schema; it only reiterates the purpose. Per the calibration baseline, a score of 3 is appropriate when the schema fully documents the parameters.

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

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

The description clearly states the tool's purpose: to retrieve example .mmt structures before creating or modifying files. It uses a specific verb ('list') and resource ('examples') and differentiates from searching the repo or guessing YAML layout, making it easy for an agent to understand its exact role.

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 states when to use the tool ('Call when you need example .mmt structure') and what to avoid ('Do not use testlight, npx, npm, shell, or node dist/mcp/server.js'). It also contrasts with the alternative of searching the repo. While it doesn't name sibling tools directly, the guidance is clear enough for proper selection.

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

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

Annotations declare readOnlyHint=true, covering the safety profile. The description adds the token-efficiency context ('min' is small) but doesn't describe return format, pagination, or error behavior. Since annotations already establish read-only nature, this is adequate but not exceptional. No contradictions found.

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 efficient, with each sentence earning its place: purpose, defaults, alternatives, and exclusions. It's front-loaded with the core trigger. Slightly long but every clause adds actionable information.

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

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

For a read-only documentation lookup with two enums and no output schema, the description covers all necessary context: when to use, parameter nuances, and explicit alternatives. An agent can confidently call this tool without additional clarification.

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 descriptions for both parameters. The description adds practical guidance beyond the schema: clarifies the 'min' vs 'full' tradeoff and that 'workflow' is the appropriate topic for MCP-first steps. This enriches the semantic understanding beyond mere enum values.

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

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

Description clearly states the tool retrieves Multimeter YAML syntax rules, a specific verb+resource. It distinguishes itself from siblings by explicitly naming scaffold_test as the alternative for new API tests and listing forbidden commands. The purpose is unambiguous and differentiated.

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

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

Provides explicit when-to-use ('Call when you need Multimeter YAML syntax rules'), defaults, when to deviate ('Use pack full only for rare/advanced syntax'), and alternatives ('prefer scaffold_test over loading docs'). Also gives explicit exclusions for testlight, npx, npm, shell, and node commands, leaving no ambiguity about 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?

With no annotations, the description carries the transparency burden. It clearly discloses the return contract (pass/fail output, logs, errors) and the exclusivity constraint, but is silent on side effects, permissions, or execution environment. It does not contradict any annotations, since none exist.

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

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

Three purposeful sentences, front-loaded with the action and output, followed by usage rules and exclusions. Every sentence earns its place with no redundancy.

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?

Strong for routing and purpose, but incomplete for a 5-parameter tool with no output schema: env and inputs semantics are missing, and the exact output shape is described only generically. Still, the common case of calling with just file is well supported.

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 documents file, quiet, and workspaceRoot (roughly 60% coverage), but the description adds little beyond clarifying that file can be a test or API file. The env and inputs parameters are completely undocumented in both the schema and description, leaving a significant gap for an agent trying to use them.

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

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

States a specific action ('Execute'), a specific resource (.mmt files), and the result (structured pass/fail output, logs, and errors). It also distinguishes itself as the 'ONLY supported way' to run .mmt files, preventing confusion with sibling tools like format or validate.

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

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

Explicitly says to call this tool directly when the user asks to run or execute, and provides an explicit exclusion list: testlight CLI, npx, npm install, shell scripts, and node dist/mcp/server.js. This leaves no ambiguity about when to use this tool versus alternatives.

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

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

Annotations provide readOnlyHint=true, and the description fully complements this by detailing the tool's output (valid YAML, suggested path, import alias, apiCard) and the recommended workflow (write, minimal edits, validate). It goes beyond the annotation by explaining what the tool returns and how the agent should proceed, with no contradiction. The description even warns against common pitfalls, enhancing transparency.

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 yet information-dense, using three sentences to convey purpose, output, and procedural constraints. It front-loads the critical 'REQUIRED first step' and delivers all necessary guidance without fluff. Every sentence earns its place, making it an efficient and structured definition.

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 that no output schema is provided, the description adequately explains the return values (test YAML, suggested path, import alias, apiCard). It also covers the workflow steps and prohibitions, providing everything an agent needs to correctly invoke and act on the tool. No critical information is missing for a read-only scaffolding tool.

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

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

The input schema provides 100% coverage of all 5 parameters, each with a description (workspaceRoot, apiPath, alias, outPath, strategy). The description does not add additional meaning to the parameters themselves—it only mentions 'import alias' as part of the output, not the alias parameter. Since the schema already documents them fully, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: to scaffold a new Multimeter test from an existing API .mmt. It specifies the verb (scaffold), the resource (test from API), and explicitly labels itself as the 'REQUIRED first step', distinguishing it from sibling tools like validate or run. It also lists what it returns, making its role unambiguous.

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

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

The description gives explicit when-to-use guidance: 'REQUIRED first step when generating a new Multimeter test from an existing API .mmt'. It also provides prohibitions ('Do not invent a blank test from scratch', 'Do not use testlight, npx, npm, shell, or node dist/mcp/server.js') and directs the agent to 'then validate', implying the correct sequence with the validate sibling. This is precise and actionable.

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 readOnlyHint annotation already signals safety, and the description adds the key behavioral fact that this tool only produces patches and does not rewrite files. It also communicates a practical constraint ('Do not use testlight, npx, npm, shell...'), which goes beyond the schema but is useful for safe invocation.

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 short and front-loaded, with the core purpose in the first sentence. The second sentence provides timing and scope, and the third adds a focused constraint; no 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 an 8-parameter tool with no output schema, the description covers what it does, when to use it, and what it will not do. Since the schema already documents all parameters, the description provides sufficient context for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds no parameter-level details beyond the schema. It does reinforce the two acceptable input sources (API outputs and body), but that information already appears in the schema's parameter descriptions.

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 action ('Suggest compact expect/assert YAML patches') and names both input sources (API outputs and/or JSON response body). It distinguishes itself from siblings by stating it is patch-only and tied to post-run or smoke-test tightening contexts rather than scaffolding or running tests.

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?

It explicitly says to use after a run or when tightening a scaffolded smoke test, and it draws a boundary with 'patch only, do not rewrite the file.' It does not name sibling tools directly, but the timing and scope give an agent enough context to choose it over run or scaffold_test.

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, covering side effects. The description adds workflow context and states the return type (structured errors and fix suggestions), but does not disclose deeper behavior such as what happens on a valid file, partial results, or validation categories.

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 short and front-loaded with the mandatory call timing, followed by the return behavior and a caution about forbidden CLI commands. There is slight redundancy between 'after every create or modify operation' and 'immediately after editing', but no significant waste.

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 read-only validation tool with a fully documented 3-parameter schema and no output schema, the description covers when to use it, what it returns, and unsafe alternatives to avoid. It would be fully complete with a bit more detail on the structure or categories of errors returned.

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 already documents all three parameters, including the expectedType enum and workspaceRoot purpose. The description adds no parameter-level meaning, so it sits at the baseline for a fully documented 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?

Title identifies the operation and resource ('Validate .mmt file'), and the description adds a concrete outcome: returns structured errors and fix suggestions. This distinguishes it from siblings like run or format, though it still leaves the exact validation scope implicit.

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

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

The description gives explicit timing: REQUIRED after every create or modify operation on an .mmt file, immediately after editing, and before telling the user the task is done. It also warns against substituting testlight, npx, npm, shell, or node dist/mcp/server.js, making the correct invocation context unambiguous.

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