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 clearly implies a read-only status check, but it does not disclose potential side effects, return format, or behavior on unresponsive ports. 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 two short sentences, with the core purpose front-loaded and no redundant wording. 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 one-parameter tool with no output schema, the description provides purpose, usage guidance, and parameter context. It is nearly complete, though it could mention the return value to fully close the loop.

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 the port parameter with 100% coverage, providing a baseline of 3. The description adds context by specifying the port is on localhost and the target is a dev server, which gives meaning beyond the raw schema 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 description clearly states the tool checks whether a dev server is running and responding on a given localhost port, using a specific verb and resource. It also distinguishes itself from sibling tools by positioning it as a prerequisite check before view_page.

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

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

The description explicitly instructs to run this tool before view_page, giving a clear usage context. However, it does not mention when not to use it or name alternative tools, so it stops short of a full 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?

No annotations are provided, so the description carries the full transparency burden. It helpfully discloses that a backup is created in .mcp-backups/ before deletion and that directories cannot be deleted. However, it does not explain restore procedures, permissions required, or behavior for non-existent files.

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 convey all essential information: the action, the backup behavior, and a key limitation. No filler or redundant content.

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

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

For a simple one-parameter destructive tool, the description covers purpose, backup behavior, and a critical limitation. The absence of an output schema makes return-value documentation unnecessary, and the backup note mitigates the need for an explicit irreversibility warning.

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 description covers 100% of the parameter (filepath) and includes 'relative to project root or absolute.' The tool description adds no additional parameter-level detail, so it relies on the schema's existing coverage.

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 action (delete a file) and its scope within the project. It also explicitly notes that directories cannot be deleted, distinguishing it from move_file or other file operations.

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 files only, since it states 'Cannot delete directories.' However, it does not explicitly compare to sibling tools like move_file or edit_file, nor does it state when to use this over 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?

With no annotations, the description carries the full transparency burden. It clearly discloses that the tool replaces the entire file and that a timestamped backup is created in .mcp-backups/ before changes, which is crucial behavioral context. It does not mention permissions or failure handling, but the core destructive nature is well covered.

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 concise sentences, front-loaded with the core purpose, followed by the backup behavior and an explicit alternative. No filler words; 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?

The description is complete for a file-write tool: it covers the operation, the destructive replacement behavior, the backup mechanism, and the preferred alternative for targeted edits. There is no output schema, but none is needed here; all important context is provided.

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 new parameter details beyond the schema, but it reinforces that 'content' is the complete new content, and the schema already documents all three properties adequately.

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: 'Write new content to a file, replacing it entirely.' It names the verb, resource, and scope, and explicitly contrasts with patch_file for small targeted changes, distinguishing it from siblings.

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 guidance: 'Use patch_file instead when making a small targeted change.' This tells the agent when to choose an alternative, fulfilling the key usage guideline requirement.

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 the full burden. It discloses the tool's read-only nature ('Shows') and specifies the information returned. It does not discuss side effects or permission requirements, but for a simple display tool this is sufficient.

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 main purpose, and each sentence contributes meaning. 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?

Given the tool's simplicity (no parameters, no output schema), the description is complete. It explains what the tool shows and when to use it. The list of returned fields partially compensates for the lack of an output schema, though the exact return format is not specified.

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

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

The tool has zero parameters, so the schema is inherently complete. According to the rubric, a 0-parameter tool receives a baseline of 4; the description adds nothing about parameters because none exist.

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 what the tool does: 'Shows which project is currently active' and enumerates specific output contents (name, root path, package info, file count, git branch). It differentiates from siblings by focusing on the active project, but does not explicitly contrast with get_project_info, so it lacks explicit sibling distinction.

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 usage context: 'Use this to visually confirm which project the MCP server is connected to.' This tells the agent when to invoke it, though it does not mention alternatives or exclusions.

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 the full burden. It discloses key behaviors: making HTTP requests, returning 'the full response', supporting all standard methods, and allowing an optional JSON body. It also scopes to local dev servers. It doesn't detail error handling or side effects, but the core behavior is transparent enough.

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 action, followed by use cases. Every word earns its place with 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?

The description covers context (local dev server), HTTP methods, request body, and use cases. It states 'return the full response' as a high-level outcome, which is helpful given no output schema. There is slight ambiguity about what constitutes the 'full response' (headers, status code, etc.), but the description is otherwise complete for a dev testing 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%, with each parameter having a clear description (e.g., method enum, path example, body format, headers example, port). The description adds no new parameter-level semantics beyond mentioning the optional JSON body and standard methods, so the 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 identifies the tool's function: 'Make an HTTP request to an API endpoint on a local dev server and return the full response.' It specifies the verb, resource (API endpoint), and scope (local dev server), which distinguishes it from sibling file/command/project 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?

The description states explicit use cases: 'Useful for testing REST APIs, checking response shapes, and verifying status codes.' This gives clear context for when to use the tool, though it does not explicitly mention alternatives or exclusions relative to sibling tools like run_command.

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 burden of behavioral disclosure. It clearly describes the expected output (metadata, scripts, deps, config files, file tree) and implies a read-only, safe operation. It could add explicit statements about non-modification, but for an info-gathering tool, the behavior is well conveyed.

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 main purpose, and contains no fluff. Every word contributes to understanding what the tool does and when to invoke it.

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 no-parameter, no-output-schema tool, the description is complete: it enumerates all major output categories, gives a clear usage directive, and is distinguishable from sibling tools. An agent can confidently decide to call it first when exploring a project.

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

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

The tool takes zero parameters, so the schema provides no meaningful information. The description compensates by explaining what the tool returns, adding context that helps an agent understand the tool's value despite the empty parameter list.

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 'Get a full overview of the project' and enumerates specific contents (package.json metadata, npm scripts, dependencies, config files, two-level file tree). This distinguishes it from the sibling 'get_active_project', which likely focuses on just the active project path.

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 guidance: 'Always call this first when starting to work on a new project.' However, it does not mention when not to use it or explicitly name alternative sibling tools for more specific queries.

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 the full burden. It describes the tree output format and implies a read-only operation through 'before reading or editing files,' but it doesn't explicitly state safety characteristics or any limitations (e.g., performance or symlink behavior). It's 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, front-loaded with purpose, zero wasted words. It states what it does and when to use it, making it 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?

Given the tool's simplicity, the description covers the main behavior and usage context. It lacks a detailed output format explanation, but no output schema is required for a listing tool. The optional parameters are fully documented in the schema, so overall completeness is strong.

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 param-specific details; it only mentions the tree output, which is not about parameters. The schema already fully explains depth and directory.

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 lists files and directories as a tree, using a specific verb ('List') and resource ('files and directories in the project'). It distinguishes from sibling tools like read_file and search_files by focusing on structural overview.

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 it to understand project structure before reading or editing files, providing clear usage context. It doesn't mention exclusions or alternatives, but the guidance is actionable and sufficient for 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?

Since no annotations are provided, the description carries the burden. It discloses that a backup is created before the move and that directories are not supported, which adds actionable behavioral detail. It omits some details like whether the backup is retained or how overwrite is handled, but the schema covers overwrite, so this is adequate.

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 concise sentences, front-loaded with the primary purpose. Every sentence adds essential information (purpose, backup, directory limitation) with no redundancy or unnecessary 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?

The description plus schema covers purpose, path types, overwrite default, backup behavior, and the directory limitation. It does not explicitly state what the tool returns or whether backups are retained, but for a straightforward move operation, the provided context is sufficient 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?

The schema already provides descriptions for all three parameters (100% coverage), so the baseline is 3. The description adds the directory restriction and backup behavior, but these are tool-level traits rather than parameter-specific semantics, so it does not significantly enhance parameter 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 moves or renames a file within the project, using a specific verb and resource. It also distinguishes from sibling tools by noting it cannot move directories, setting it apart from general file operations like read_file or delete_file.

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 that this tool is for moving/renaming files within the project and excludes directories. However, it does not explicitly name alternatives or state when not to use it (e.g., for moving directories), so it lacks explicit exclusions/alternatives that would earn 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?

With no annotations provided, the description carries the full burden and discloses key behavioral traits: it automatically creates a backup and enforces uniqueness of the old_string. It does not mention error handling for non-unique matches or permission requirements, but the disclosed traits (backup, targeted modification) are valuable and not redundant with 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 just two sentences, tightly written with no filler. It front-loads the primary action and includes the most critical constraints and side effects without unnecessary elaboration.

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 3-parameter tool with no output schema, the description covers the essential aspects: what it does, the uniqueness constraint, and the automatic backup side effect. It lacks explicit error-behavior details, but for this complexity level the description is sufficiently 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 100%, and each parameter already has a clear description. The tool description reinforces the uniqueness requirement for old_string but does not add new parameter-level meaning beyond what the schema already provides, so the baseline 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 uses a specific verb 'Replace' and a clear resource 'a specific string or block of code within a file', and adds the scope 'without rewriting the whole file' which distinguishes it from whole-file editing tools like edit_file. This makes the purpose unmistakable.

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: for targeted, minimal changes without rewriting the whole file. It also states a critical precondition (old_string must appear exactly once), but it does not explicitly name alternatives or when-not-to-use scenarios beyond the implied whole-file rewrite exclusion.

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 the read operation and the optional line-range limitation, but it does not mention error behavior (e.g., file not found), encoding, or whether the read is safe in terms of side effects. The range-limiting behavior is also already described in the schema, so the added transparency is minimal.

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 first sentence states the core purpose, the second adds the optional line-range feature, and the third gives practical path guidance. Every sentence earns its place; no redundancy or irrelevant details.

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 3 parameters and full schema coverage, the description is adequately complete. It implies the return value by saying 'Read the contents,' and it includes a helpful prerequisite tip. It does not explain failure modes or output format, but given the simplicity, a 4 is appropriate.

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 new meaning for filepath, start_line, or end_line beyond the schema's definitions. The tip about using list_files is more of a usage guideline than parameter semantics, so it does not raise the score above 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 clearly states 'Read the contents of a file in the project,' identifying the specific verb 'read' and resource 'file.' This unambiguously distinguishes from siblings like edit_file, delete_file, and list_files, and the word 'project' scopes the tool appropriately.

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 a clear usage guideline: 'Use list_files first if you are unsure of the file path.' This tells the agent when to invoke a predecessor tool, but it does not explicitly mention alternative tools like view_page or list exclusions, so it falls short of a full 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?

No annotations are provided, so the description carries the burden. It discloses the important allowlist restriction and cwd behavior, but does not mention output format, exit code handling, or potential side effects beyond schema's timeout. 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: first focuses on action and location, second lists use cases and the key restriction. Front-loaded, no redundancy, 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?

For a 3-param tool with no annotations and no output schema, the description covers purpose, typical uses, and the allowlist constraint. It may not describe return values, but command execution output is intuitive. Overall sufficiently complete for agent selection and 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 description coverage is 100%, so the schema fully documents all three parameters. The description adds minimal extra context (monorepo use for cwd), but does not need to compensate for any gaps. 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 uses a specific verb ('Run') and clearly identifies the resource ('allowlisted shell command') with context (project root or subdirectory). It is unambiguously distinct from sibling file/project tools like read_file and get_project_info.

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 lists common use cases (installing dependencies, tests, linting, type-checking, builds) and provides monorepo guidance for `cwd`. No explicit alternatives are needed because siblings serve different functions, though 'when not to use' is not stated.

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 of behavioral disclosure. It transparently states that it skips node_modules, hidden directories, and binary files, and describes the return data. This exceeds basic expectations, though it could mention performance or edge cases.

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

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

The description is two sentences, front-loaded with the primary action and return value, followed by filtering options and exclusions. Every sentence adds value, with no redundancy or unnecessary 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?

Given the absence of an output schema and annotations, the description is remarkably complete. It conveys the tool's purpose, parameters (via examples), return format, and exclusion behavior, giving an agent everything needed 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?

All 5 parameters are fully described in the schema (100% coverage), so the description adds only minimal value beyond the schema. It mentions a file glob example and regex/text search, but these are already covered by the 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 clearly identifies the tool as a search for text or regex across project files, with specific details about return values (file paths, line numbers, matching lines). This distinguishes it from sibling tools like list_files or read_file, which serve different purposes.

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 tool is for searching file contents across the entire project, with optional filters like file glob. It provides clear context but does not explicitly mention when not to use it or name alternative tools, 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It explains what the tool returns (title, meta tags, script sources, visible text, optional raw HTML) but does not mention whether it executes client-side JavaScript, how it handles missing pages or server errors, or that fetching may be a read-only operation. It adds some useful context but lacks caveats about limitations.

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 concise sentences with the main action front-loaded. The first sentence states what it fetches, and the second sentence lists return values including the optional raw HTML. No wasted words, 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 has 3 parameters, no output schema, and no annotations, the description provides a solid overview of purpose and expected return contents. It lists the main categories of data returned, which is enough for an agent to understand the tool's output, though it doesn't specify the exact JSON structure or error behavior. This is slightly above the minimum viable level.

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 input schema already documents all three parameters (path, port, include_raw_html) with descriptions and defaults. The tool description adds no parameter-level meaning beyond what the schema provides, so the 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 fetches HTML content and structure from a page on a local dev server, naming specific return items (title, meta tags, script sources, visible text). This distinguishes it from siblings like get_api_response (API responses) and read_file (file contents), making the tool's 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 implies when to use the tool: when you need to inspect the HTML of a page served by a running local dev server. It does not explicitly contrast it with alternatives like get_api_response or check_port, but the context and the mention of 'dev server' provide clear usage context without exclusions.

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