MCP Observatory

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

Describes key behaviors: launches server, checks capabilities, saves artifact. Explains deep and security parameters' effects. No annotations, so description carries burden; it is thorough but could mention if there are any 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 plus an example; no fluff. Purpose front-loaded, each sentence adds information. Highly efficient.

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

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

For a testing tool with 4 parameters and no output schema, description explains all necessary usage, example, and parameter purposes. Complete for its complexity.

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

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

Schema coverage is 100%, providing baseline. Description adds value by explaining deep and security flags beyond schema descriptions, and gives a concrete example.

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 tests a specific MCP server before installation or after update, with actions: launch, check capabilities, save artifact. It distinguishes from siblings by focusing on testing rather than scanning or scoring.

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

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

Explicitly says when to use (pre-install, post-update), providing clear context. Lacks explicit when-not-to-use or alternatives, but the purpose is well-defined.

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 full burden but only states it generates a report, implying a read operation. It does not disclose side effects, required permissions, or output format, leaving significant ambiguity.

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, focused sentence of 9 words, perfectly front-loaded and efficient with no extraneous content.

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

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

Given the simple schema (1 optional parameter) and no output schema, the description lacks specifics about the report's nature, contents, or return value, leaving the agent insufficiently informed for correct invocation.

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 baseline is 3. The description adds no new meaning beyond the schema's parameter details, merely echoing 'from run artifacts', which is already apparent.

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 'Generate a CI regression report from run artifacts' uses a specific verb (Generate) and resource (CI regression report from run artifacts), clearly distinguishing it from sibling tools like get_last_run or scan.

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 offers no guidance on when to use this tool versus alternatives, such as diff_runs or check_server, nor does it specify prerequisites or context.

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

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

Describes what the tool surfaces (changes, regressions, etc.), but with no annotations, the description lacks information on side effects, permissions, or whether it reads/writes. The behavior is implied but not fully transparent.

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 purpose, no fluff. Every sentence adds value.

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

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

Covers the main use case and output types, but lacks details on output format (though format parameter is in schema) and prerequisites like file existence. Given no output schema, it is fairly 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 covers all parameters with descriptions; the description adds context about the comparison but does not provide additional semantics beyond the schema for each parameter.

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 it finds changes between two run artifacts, listing specific types (regressions, recoveries, schema drift, gate status changes). However, it does not differentiate from sibling tools that may also compare runs or history.

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 a specific use case 'Essential after updating a server', but does not include when to avoid using it or alternative tools for similar tasks.

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 should disclose behavioral traits. It states it 'gets' data (read operation) but does not mention potential impacts, auth requirements, or rate limits. The behavior is minimally transparent.

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

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

The description is a single sentence of 10 words, highly concise and front-loaded with the core purpose. No unnecessary words.

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

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

Given no output schema, the description should explain the return format (e.g., list of scores, timeline). It does not. Also missing details about required run history context. Incomplete for a tool with no 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 coverage is 100% with a single parameter described. The description adds no additional meaning beyond the schema, so 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 retrieves health score trends from run history, using a specific verb and resource. However, it does not explicitly distinguish from sibling tools like get_last_run or diff_runs.

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

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

No guidance is provided on when to use this tool versus alternatives such as get_last_run (single result) or diff_runs (comparison). The description lacks context about appropriate use cases.

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 provided, the description carries the full burden of behavioral disclosure. It states the operation returns data and adds context about handshake details and that no account is needed. However, it does not explicitly mention that this is a read-only operation, what happens if no run exists (e.g., returns null or errors), or any other behavioral nuances. It adds some value but lacks full 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 two sentences, front-loaded with the primary purpose, and includes only essential additional context (handshake detail and no-account requirement). There is no wasted wording; every clause 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 is simple (one parameter, no output schema), the description covers the main operation and a key prerequisite. It would be more complete with a note on error handling (e.g., what happens if no run is found) or a mention that it's read-only. However, for its complexity, it is nearly complete and clear enough for an agent.

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% for the single parameter `targetId`, which already includes an explanation. The tool description adds minimal semantic value beyond the schema—it repeats that it's for a server, but does not elaborate on the format, required patterns, or how it is used in the operation. The description is adequate but not enriching.

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: 'Return the last Observatory run for a server'. It specifies the resource (Observatory run), the scope (last run for a server), and adds a distinctive detail (including handshake allow/deny). This differentiates it from siblings like get_history (which likely returns all runs) and check_server (which likely checks status).

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It mentions 'No hosted account required', which is a prerequisite/condition, but does not say 'use this to get the most recent run' or contrast it with siblings like get_history or scan. The usage context is only implicit.

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?

No annotations are provided, so the description carries full burden. It states what is detected but omits key behavioral traits: whether the tool is read-only, whether it modifies state, what triggers an error, or how the result is presented. For a verification tool, these gaps reduce 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?

One concise sentence that conveys the core purpose without wasted words. Information density is high.

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 complexity (verification against a lock file) and no output schema, the description should hint at the return format (e.g., boolean, diff report). It doesn't explain what a lock file is or how it is created, assuming context from sibling tools. Adequate but with 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 single parameter 'config' has a description in the schema ('Path to MCP config file.'). The tool description does not add any additional information about the parameter, such as format, defaults, or how it relates to the lock file. With 100% schema coverage, baseline is 3.

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 verb 'verify' and the resource 'live MCP servers match a previously saved lock file'. It specifies the exact purpose: detecting schema drift, added/removed tools, and breaking changes. This distinguishes it from sibling tools like 'verify' (generic) and 'check_server' (single server check).

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?

Description implies usage context (when a lock file exists and drift detection is needed), but does not explicitly say when to use this tool vs alternatives. No exclusions or prerequisites are provided. With nine siblings, more guidance would be helpful.

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 full burden. It explains the core behavior (records all JSON-RPC traffic to a cassette file) and mentions offline replay capability. However, it lacks details about side effects, required permissions, or the format of the cassette file.

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 (three sentences), front-loaded with the purpose, and uses an analogy ('Like VCR for MCP') for clarity. Every sentence adds value.

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 parameters, no nested objects), the description is largely complete. However, it does not explicitly state the return value (e.g., the path to the cassette file), which would be helpful for an AI agent using the 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?

All parameters are described in the input schema (100% coverage). The description does not add any additional semantic meaning beyond what the schema already provides, so a baseline score 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: capture a baseline of a working MCP server by recording JSON-RPC traffic to a cassette file. It uses a specific verb ('capture', 'records') and resource, and distinguishes from siblings like 'replay' and 'verify'.

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 clear context for when to use the tool (to capture a baseline for offline replay or verification), but it does not explicitly state when not to use it or mention alternatives among siblings. The context is sufficient for an AI agent to decide.

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 discloses that the tool runs offline and replays recorded responses, but does not specify side effects (e.g., no modifications) or output format. Since no annotations are provided, the description carries the full burden and could be more detailed.

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 three sentences, front-loaded with purpose, and every sentence adds value. No unnecessary words.

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

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

The description explains purpose, behavior, and use cases but does not mention the output format or return value, which is important since no output schema is provided. For a simple tool, it's adequate but incomplete.

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 description for the 'cassette' parameter. The description adds no additional semantic value beyond the schema, so 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 replays a recorded cassette to test a server offline, which is a specific verb-resource combination. It distinguishes from sibling tools like 'check_server' which likely test live servers.

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 mentions usefulness in CI or when the live server is unavailable, giving clear context for when to use. It lacks explicit when-not-to-use or alternative mentions, but the context is strong enough.

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?

No annotations present, so description fully covers behavior: auto-discovers servers from config files, connects, verifies responses, and in deep mode invokes tools. Discloses return is pass/fail status.

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?

Concise paragraph with front-loaded purpose, followed by parameter guidance. Every sentence adds value; no wasted words.

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

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

Complete description for a health-check tool with 3 optional parameters and no output schema. Explains return format, auto-discovery, and verification steps.

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 covers 100% of parameters with descriptions. Description adds usage context (e.g., deep=true invokes tools, config path specific, security analysis) beyond 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?

Clearly states it checks MCP server health with auto-discovery and verification of tools/prompts/resources. Distinguishes from siblings like check_server (single server) and verify (different scope) by describing the comprehensive health check.

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 'Use this to check if all your MCP servers are healthy' and suggests when to use deep=true. Does not mention when not to use or alternatives, but provides sufficient 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?

No annotations are present, so the description carries full burden. It states 'runs all checks' but does not disclose potential side effects (e.g., launching a server or modifying state), whether it requires permissions, or what happens on failure. This is insufficient transparency for a tool that executes commands.

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 sentences long, front-loaded with the primary use case, and efficiently enumerates the checks and output. No unnecessary words; each sentence adds value.

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

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

Given the tool has no output schema, the description adequately explains the return value (0-100 score, A-F grade, breakdown across multiple dimensions). It lists the areas checked but could mention prerequisites (e.g., server must be running) or result interpretation.

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 additional meaning beyond the schema's parameter descriptions; it merely repeats the concept of 'command' and 'args' without deepening understanding.

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 action ('get a quick health grade') and the target ('an MCP server'), listing the checks performed and output format. It is distinct from sibling tools like 'scan' or 'check_server' but does not explicitly differentiate itself.

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 mentions 'Use this to get a quick health grade', implying usage context. However, it does not provide when-not-to-use guidance or compare with alternatives such as 'verify' or 'check_server' for more detailed checks.

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?

No annotations provided, so description carries full burden. It describes scanning, listing, and cross-referencing behavior but does not disclose potential side effects, network usage, error handling, or whether it modifies any files. Adequate but not detailed.

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, no wasted words. First sentence gives usage context, second explains the process. Front-loaded and efficient.

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

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

Given the tool's complexity (scanning, listing, cross-referencing) and no output schema, the description explains input and general behavior but does not specify the output format or what exactly 'recommend servers you're missing' means. Slightly incomplete but still good for a suggestion 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?

Only parameter 'cwd' has schema description 'Working directory to scan for environment signals. Defaults to process.cwd().' Description adds context about the scanning purpose, but the schema already covers the meaning. With 100% schema coverage, 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 scans working directory for languages, frameworks, databases, and cloud providers, lists configured servers, and cross-references the MCP registry to recommend missing servers. It sets it apart from siblings like 'scan' or 'check_server' by focusing on recommendations for project setup.

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 'Use this when setting up a project or wondering what MCP servers to add.' Provides clear context for when to use, but does not mention when to use alternative sibling tools like 'scan' or 'check_server' instead.

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 full burden. It explains key behaviors: connects to live server, sends requests from a recorded cassette, compares responses, and reports changes. It lacks details on potential side effects (e.g., read-only nature) or prerequisites, but covers core actions well.

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 at two sentences, with no redundant information. Every sentence adds value, clearly stating purpose, method, and output.

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 no output schema, the description partially explains the output ('reports exactly what changed'). However, it doesn't specify the format or structure of the report, which could be critical for programmatic use. Otherwise, context is sufficient for a verification tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no new information beyond the schema parameter descriptions (e.g., 'path to cassette', 'command', 'args'). It does not enhance semantic understanding.

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: verifying a server after an update by comparing responses against a recorded cassette. It specifies the verb ('confirm nothing broke') and resource ('server'), and effectively distinguishes from sibling tools like 'record' and 'replay'.

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 explicit context for when to use ('after updating a server'), which is helpful. However, it does not mention when not to use it or name alternative tools (e.g., 'replay' vs 'verify'), leaving some ambiguity.

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 full burden. It discloses that the tool runs all checks, saves results, diffs against previous runs, and shows regressions, recoveries, and schema drift. It does not mention side effects or auth needs, but the behavioral description is comprehensive for the tool's purpose.

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

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

Three sentences with no wasted words. The purpose is front-loaded, and every sentence adds value. Excellent conciseness.

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

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

Despite no output schema, the description explains what the tool shows (regressions, recoveries, schema drift). It clarifies that a previous run is needed by mentioning 'since the last check' and 'previous run for the same target.' Complete for its complexity.

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

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

Schema coverage is 100%, so the schema already describes both parameters (command and args). The description adds no additional parameter meaning, so baseline score 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 it checks a server and shows changes since last check, specifying verb, resource, and scope. It distinguishes from siblings like 'scan' and 'diff_runs' by noting it runs all checks, saves results, and diffs against previous runs in one call.

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

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

The description says 'Use this to check a server and see what changed since the last check,' providing clear context. It implies a usage scenario but does not explicitly mention when not to use or provide alternatives. Still, the guidance is strong.

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