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

With no annotations, the description carries the full burden and it explicitly opens with 'READ ONLY', preventing an agent from misclassifying this as a mutating operation. It also discloses what the function returns, i.e., differences categorized under specific terminology. It does not detail input validation, error behaviors, or performance implications, but for a read-only comparison this is the key behavioral fact.

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 short sentences, with the most critical safety cue ('READ ONLY') front-loaded. Every sentence contributes distinct information: safety, core action, output terminology, and use context. There is no filler or irrelevant 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 covers the core behavior, return terminology, and a clear use case, and the presence of an output schema removes the need to detail return structure. It is missing a bit of guidance on issues like path meaning or the meaning of max_results, but for an agent deciding whether to invoke this tool, the provided context is sufficient.

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

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

Schema description coverage is 0%, so the description must compensate for the two required parameters. 'Between two phases' indicates from_phase and to_phase semantics, but it omits path and max_results entirely. The description does not clarify possible phase value formats, how max_results applies, or when to customize the default path.

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 clear verb-resource combination ('Compare documentation evidence between two phases') and defines a distinctive result set of terminology ('EXISTING, RESOLVED, NEW, POTENTIAL REGRESSION, UNKNOWN'). This differentiates it from sibling tools like mcquest_phase_context or mcquest_find_evidence, which do not signal comparison across phases.

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 the intended use: 'Use to understand what changed between phases.' This gives clear context for when to invoke the tool. It does not name alternative tools or exclusions, so it misses the full 'when-not-to-use' guidance.

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

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

With no annotations provided, the description carries the full disclosure burden. It explicitly labels the tool as 'READ ONLY' and explains that results are grouped into code and documentation evidence. It does not go into rate limits, authentication, or caveats, but the main behavioral traits relevant to an agent are disclosed.

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, front-loads the critical READ ONLY label, and each sentence adds a useful piece of information: combined search scope, grouped output, valid scopes, optional phase filter, and when to prefer this tool. No wasted wording.

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 output schema is available, so return-value details need not be repeated. The description covers the essential usage context, result grouping, scope values, phase filtering, and read-only behavior. It only lacks a clearer explanation of how 'path' and 'docs_path' relate to the different evidence categories, but this is not a major gap given the defaults in the schema.

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

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

Schema description coverage is 0%, so the description must supply meaning beyond the parameter names. It does explain 'scope' and the optional 'phase' filter, but it leaves 'path', 'docs_path', 'max_results', and 'context_lines' without any descriptive addition, relying on their default values in the schema.

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

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

The description states a clear verb-resource relationship: 'Search across code, documentation, and phase evidence in a single call.' It also specifies the result grouping ('CODE EVIDENCE and DOCUMENTATION EVIDENCE'), which distinguishes it from generic search siblings like mcquest_search and mcquest_search_docs.

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 final sentence gives explicit guidance: 'Use this instead of separately searching code and docs.' This effectively tells an agent when the combined tool is appropriate, although it does not explicitly name sibling tools or state exclusions such as 'use mcquest_read_file when you need exact file contents.'

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 full burden for behavioral disclosure. It leads with 'READ ONLY' and also discloses case-insensitive matching and relative-path output. This is solid, though it could additionally clarify search-root behavior or default result limits.

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 purposeful sentences with no filler. The most important caveat, READ ONLY, is front-loaded, followed by what it does and when to use 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?

The tool is simple and the output schema covers return structure, so the description need not restate that. It adequately covers the key behavior and usage context, but the unclear semantics for 'path' and 'max_results' leave a small completeness gap.

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

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

The schema has 0% description coverage, so the description must compensate. It clarifies that 'query' is a filename substring and that results are relative paths, but it does not explain the 'path' or 'max_results' parameters. Those remain only inferable from their names and defaults.

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

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

The description uses a specific verb and resource ('Find project files'), states the matching behavior ('filename using case-insensitive substring matching'), and specifies the output ('Returns relative file paths'). This clearly distinguishes the tool from siblings like mcquest_list_files or mcquest_search.

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 a clear trigger: 'Use when you know a filename but not its location.' It does not explicitly name when-not-to-use conditions or alternatives, so it falls just 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?

No annotations are provided, so the description carries the full burden. It clearly states 'READ ONLY', enumerates searched file extensions, and describes the output format as 'file:line:import-statement'. This gives the agent a solid understanding of scope and side-effect safety beyond the bare 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?

Two sentences contain zero filler. The 'READ ONLY' safety qualifier is front-loaded, followed by a precise statement of the action, scope, and output format. 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?

The tool is simple and an agent can likely invoke it with 'target' and the default path. However, the description does not mention that 'path' is the directory to search or that 'max_results' limits output, and with 0% schema coverage those details remain underspecified. The output schema exists, so return-value documentation is not required here, but parameter gaps remain.

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

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

Schema description coverage is 0%, so the description must compensate for parameter documentation. It clarifies that 'target' is a component/module, but it does not explain 'path' or 'max_results' beyond what their names imply. The description adds some semantic value for the main parameter but leaves the other two largely implicit.

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

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

The description states a specific verb and resource: 'Find ES module imports that reference a target component/module.' It also scopes the search to .ts, .tsx, .js, and .jsx files. It does not explicitly distinguish itself from siblings like mcquest_find_usages, but the import-specific phrasing makes the differentiation reasonably clear.

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 'Useful for discovering which files depend on a module,' which implies a primary use case. However, it does not name alternatives or explain when to prefer this over siblings like mcquest_find_usages or mcquest_find_files. The usage context is present but not fully explicit.

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 behavioral burden. It explicitly adds READ ONLY and the important behavior of word-boundary matching, which materially affects results. But it leaves key behaviors undisclosed: case sensitivity, ordering, behavior at max_results, and whether file_pattern expects a glob or regex.

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 tight, front-loaded sentences: the read-only status first, the core action second, the output shape and use case third. Every sentence earns its place and the description is under 40 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 core purpose, output format, and a key matching behavior are present, and an output schema exists to cover return values. Still, with zero annotations and zero schema descriptions, the tool description should also clarify the default scope of frontend/src, file_pattern semantics, and max_results cutoff behavior; those gaps prevent agents from tuning the four parameters confidently.

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

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

Schema description coverage is 0%, so each parameter relies on the description to compensate. Only the symbol parameter gains semantics (references found via word-boundary matching); path, max_results, and file_pattern get no explanation of their interpretation or interplay, leaving the agent to guess at meaningful 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?

The description states a specific verb and resource ('Find references to a symbol across MCQuest source files'), a matching mechanism (word-boundary matching), and a concrete return shape (file:line:line-content). This differentiates it from nearby siblings such as mcquest_find_imports, so an agent can pick it without opening any schema.

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

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

'Use for discovering where a component, function, or variable is used' gives a clear when-to-use context. However, it does not name exclusions or point to alternatives — for example, it never explains when to prefer mcquest_search or mcquest_find_imports instead — so it falls short of a perfect 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 bears the full behavioral transparency burden. It clearly states the tool is read-only and lists the mutating operations it will never perform, which gives an agent confidence about safety. It also names the exact categories of information returned, making behavior predictable without over-explaining.

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

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

The description is compact and front-loaded with 'READ ONLY,' which is high-signal for an agent triaging tool safety. The enumeration of non-performed operations is a bit long but earns its place by preventing incorrect use. Minor redundancy between 'READ ONLY' and 'read-only Git investigation information' exists, but it does not hurt clarity.

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

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

The description covers the tool's main output categories and safety boundaries, while the presence of an output schema reduces the need to explain return values. However, because the parameters are undocumented and there are no annotations, an agent may still be uncertain how the limits are applied. This is a moderate completeness gap for a tool with two configurable parameters.

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

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

Schema description coverage is 0%, and the description does not mention max_changes or max_commits at all. The parameter names and defaults in the schema are somewhat self-explanatory, but the description does not clarify whether limits apply to changed files, commits, or both. Given the lack of schema docs, the description should have compensated and did not.

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 with a specific verb and resource: 'Provide read-only Git investigation information.' It enumerates concrete outputs — branch, working-tree status, commits, changed files — and explicitly says it does not perform write operations. It does not differentiate from sibling tools by name, but the Git focus and non-mutating scope set it apart.

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

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

The final sentence gives direct usage guidance: 'Use to understand recent changes and current branch state.' The description also lists operations the tool does not perform, helping an agent avoid invoking it for commits, pushes, merges, and similar actions. It does not name alternative tools or say when another sibling should be used 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?

No annotations are provided, so the description must carry the behavioral disclosure burden. It opens with 'READ ONLY', states exclusions for dependency/generated directories and non-Markdown files, and reports that it returns relative file paths. This goes beyond a simple list operation and gives the agent a clear safety and scope model.

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: four short sentences, with the most important reading-safety flag first, followed by scope and return type. Every sentence adds functional information. It is not overly verbose, though the second sentence could be merged somewhat without damage.

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 modestly complex tool with three optional params and an output schema, the description covers the important functional boundaries: read-only, Markdown only, generated-dir exclusion, and relative-path returns. The output schema presumably specifies the result format, so the absence of that detail is not a concern. Minor gaps remain around how path is interpreted and whether the listing is recursive, but these do not undermine 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 input schema provides zero descriptions (0% schema description coverage), and the description does not explain any of the three parameters. 'path' and 'pattern' are only implicitly tied to 'under a project directory' and 'Markdown files'. The behavior with 'max_results' is entirely undocumented. The description fails to compensate for the schema's total lack of parameter guidance.

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 precise verb ('List') and a specific resource ('Markdown documentation files under a project directory'), and makes an explicit exclusion ('non-Markdown files'). This clearly distinguishes it from sibling tools like mcquest_list_files, which lists all files. The action and scope are unambiguously stated.

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

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

The description gives an explicit use case: 'Use to discover available documentation before reading specific files.' This tells the agent when it is appropriate to call the tool and even suggests sequencing relative to read_doc. However, it does not mention any alternatives or when not to use it, so it stops just 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?

There are no annotations provided, so the description carries the full behavioral burden. The description importantly discloses that the operation is read-only, lists source files, excludes large generated and dependency directories, and returns relative paths. It does not mention how pattern or max_results affect behavior, but the core operational expectations are well disclosed.

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, frontloaded with the essential 'READ ONLY' safety signal, and every sentence adds relevant detail. The formatting is clean and easy to scan. There is no wasted content or unnecessary repetition.

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

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

For a simple listing tool, the description covers the central use case well, including scope, exclusions, and output form. However, it leaves pattern and max_results semantically thin, and the small amount of guidance about alternatives is not fully complete. An agent could invoke it correctly with the defaults, but would benefit from clearer behavior description.

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

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

Schema description coverage is 0%, and the description only loosely addresses the path concept by talking about project directories. The pattern and max_results parameters are not explained at all, and their meaning must be inferred from their names and defaults. This is a meaningful gap because the description does not compensate for the missing schema 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 uses a specific verb and resource ('List source files under a project directory') and clarifies the tool returns relative file paths. It clearly indicates what is excluded, which helps define scope, but it does not explicitly differentiate from the sibling find_files tool. Overall, purpose is clear enough for an agent to understand the operation.

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

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

It explicitly says to prefer this over searching when the directory to inspect is known, giving practical guidance. The statement implies the alternative is a search-based approach for less precise exploration. It does not enumerate all sibling tools or exclusions, but the primary usage context is clear.

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

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

No annotations are provided, so the description carries the full burden. It opens with 'READ ONLY' and states 'Returns evidence only — no modifications,' which strongly signals that the tool is non-mutating. It does not disclose more granular behavioral details, but the safety-relevant behavior 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 compact, front-loaded with the read-only warning, and contains no filler. The category enumeration is long but directly useful to the agent and 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?

With an output schema present, the description does not need to explain return values. It covers the tool's purpose, valid categories, default path, and use case. The missing semantics for 'path' and 'max_results_per_category' are minor gaps since both have defaults and the tool is otherwise simple.

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

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

Schema description coverage is 0%, so the description must compensate. It fully documents the 'categories' parameter by listing every valid value, but it does not explain 'path' semantics or what 'max_results_per_category' actually controls, leaving two of three parameters to inference.

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 a specific action — running predefined MCQuest responsive/layout pattern searches — and names the resource being audited. It also lists the exact categories, which distinguishes it from the generic search/read/list sibling 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 explicitly says 'Use for auditing potential mobile/responsive issues,' giving the agent a concrete context for when to call it. It does not explicitly name alternatives or exclusions, but the intended use case 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so well. It explicitly states READ ONLY, explains what happens when phase and query are supplied, describes grouping behavior, return context, and claims to preserve original evidence while working for both past and future phases.

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

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

The description is compact and front-loaded with 'READ ONLY' and 'Locate relevant phase/stage documentation' before moving into usage details. Every sentence adds value, and the examples are specific without being verbose.

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 reasonably complete because the output schema already covers the return shape, and the description clarifies the main usage mode, grouping, and scope. It is missing guidance on during what circumstances a caller should prefer another sibling tool, but the core behavior and key parameter semantics are present.

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

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

The description adds meaningful semantics for the two central parameters, 'query' and 'phase', including examples like 'responsive overflow', 'Android', '61', and '61-Part-II-A'. However, it does not explain the remaining parameters such as max_results, context_lines, include_audits, or include_implementation, despite the schema having 0% description 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 that this tool locates phase/stage documentation and frames it as read-only, which gives an agent a specific verb and resource. It does not explicitly name sibling tools or draw a boundary against them, but the 'phase/stage documentation' scope is distinct enough among the sibling list.

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 practical usage guidance for the query and phase modes, including concrete examples and the grouping behavior when phase is used. However, it does not state when to choose this tool over siblings such as mcquest_search_docs, mcquest_project_context, or mcquest_compare_phase, so the tool-selection guidance is only implied.

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 behavioral transparency burden. It clearly states READ ONLY and disclaims exhaustiveness with 'compact high-level understanding', which signals the tool is not a deep-dive and sets expectations about scope. No contradictions or hidden side effects are present.

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 with the READ ONLY safety signal front-loaded, followed by a concise list of what the tool returns and a clear usage recommendation. Every sentence adds value and there is no padding.

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 zero-parameter tool with an output schema, nothing critical is missing. The description states the purpose, the scope of information returned, and the best time to use it, making it complete in context.

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 and schema description coverage is 100%, so there is no parameter ambiguity. The description adds the semantic context that the tool is a high-level overview rather than a detailed investigation, which is appropriate for a parameterless interface.

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: providing a compact high-level understanding of the MCQuest project, including technology stack, directories, and key files. This is distinct from file listing or search tools, though it does not explicitly differentiate from the similarly named mcquest_project_info sibling.

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 recommends using this tool as the first context call before a large investigation, which gives concrete usage timing. It does not list exclusions or compare against alternative siblings, but the guidance is sufficient for a zero-parameter contextual 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?

No annotations are provided, so the description carries the full burden. It leads with 'READ ONLY', explicitly signaling that the tool is safe and non-mutating, and then explains what it returns. For a zero-parameter read-only informational tool, this level of behavioral disclosure is adequate, although it doesn't mention potential latency or internal behavior.

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

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

Three short sentences are used: the read-only hint, the action and scope, and the usage recommendation. Everything is front-loaded and each sentence pulls its weight without 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 tool has zero parameters and an output schema exists, so the description does not need to detail return structure. It provides purpose, expected contents, and a clear invocation time, making the information complete for an agent to select and call 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?

The tool has zero parameters and schema description coverage is 100% by definition. With no parameters to explain, the baseline of 4 applies; the description adds nothing about parameters but nothing is needed.

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 verb 'Get' and the specific resource 'a compact overview of the MCQuest project structure', listing the exact outputs: project root, top-level directories, and key configuration files. It is easy to tell apart from file-level or search tools, but it does not explicitly distinguish itself from the sibling 'mcquest_project_context', so it falls short of full sibling differentiation.

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

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

The description says 'Use this as the first context call before a large investigation,' which gives an explicit, direct usage time. It does not state when not to use it or name alternatives, but the contextual cue is strong enough for proper 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 provided, the description carries the full behavioral burden. It clearly declares the read-only nature, exact line numbering, line-range recommendation, and the line-numbered Markdown output. It does not disclose error behavior or invalid-range handling, but the core behavior is 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 short and front-loaded with purpose and safety. Slight redundancy exists between 'READ ONLY' and 'Read' and between 'exact line numbers' and 'line-numbered', but overall each sentence adds useful 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?

Given the simple resource type, the presence of an output schema, and the small parameter set, the description covers the essential behaviors an agent needs to invoke the tool correctly. The main gap is not explaining how this differs from the closely related mcquest_read_file sibling.

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 has zero parameter descriptions, so the description must compensate. It does explain the meaning of line ranges, covering start_line and end_line reasonably, and 'path' is made obvious by 'Markdown documentation file'. Still, it leaves path details and edge-case semantics underspecified.

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 a Markdown documentation file as the resource, and 'read' as the verb. It also adds the line-numbered output behavior, which helps distinguish it from plain file reads and the similar sibling mcquest_read_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 concrete usage guidance: use line ranges instead of requesting huge files. However, it does not state when to prefer this over sibling tools like mcquest_read_file or when not to use it.

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 leads with 'READ ONLY', disclosing the operation's safety profile in the absence of annotations. It also states the output format and advises range usage, giving useful behavioral context beyond the bare 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 short, front-loaded with the most important signal ('READ ONLY'), and gives practical advice. Minor redundancy exists between 'exact line numbers' and 'returns line-numbered content', but overall there is no padding.

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 the tool has only three simple parameters and an output schema, the description covers the key points: what to read, the line-range preference, and token efficiency. It is slightly thin on default behavior, but not critically 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 description coverage is 0%, and the description only indirectly references line ranges. It does not explain how `start_line` and `end_line` behave, whether the range is inclusive, how `path` is resolved, or what the defaults imply.

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

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

The description states a specific verb-resource action: read a source file. It also clarifies the output ('line-numbered content') and distinguishes this from doc-reading and search tools by specifying 'source 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?

It gives explicit operational guidance: use line ranges instead of full files to reduce token consumption. It doesn't explicitly name sibling alternatives or exclusions, but 'source file' clearly frames the intended use.

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 full behavioral burden. It starts with 'READ ONLY' and describes what the operation returns, including 'limited surrounding context,' giving agents a useful safety and scope profile. It could add more about limits but covers the core behavior 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?

Compact and front-loaded with the 'READ ONLY' safety cue, followed by the operation and return details. Every clause earns its place and no filler is present.

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 output schema covers the basic invocation, and role plus schema defaults cover much of the rest. Still, with zero parameter descriptions and several sibling search tools, it would benefit from one sentence clarifying file_pattern or when to use the doc search variant.

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

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

Schema description coverage is 0%, yet the description adds meaning only for pattern by saying it's a regular expression. The remaining parameters—path, max_results, file_pattern, context_lines, and case_sensitive—rely entirely on their titles and defaults, so the description does not compensate for the low schema 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?

Describes a specific operation—search MCQuest source files using regex—and explicitly mentions the output (paths, line numbers, matching lines, surrounding context). It differentiates on resource type by saying 'source files', but it does not name sibling tools, so it stops short of the full 5 rating.

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 phrase 'prefer this for locating code patterns' gives a clear general context. However, it provides no explicit when-not-to-use or alternatives, leaving the agent to infer how this differs from mcquest_search_docs and other sibling search/list tools.

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

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

No annotations exist, so the description carries the full burden. Explicitly labeling it 'READ ONLY' and describing the outputs (exact file paths, line numbers, matching lines, limited surrounding context) gives the agent actionable behavioral expectations beyond the tool name.

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 short sentences with no filler, and the safety-relevant 'READ ONLY' is front-loaded. Every sentence contributes.

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 tool's output and read-only behavior are clear, and the output schema plus default-valued parameters fill some gaps. However, with six parameters at 0% schema description coverage, the description should explain more about how path, file_pattern, context_lines, and max_results shape the search.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meanings, but it mentions only pattern ('regex or text pattern') and only indirectly 'limited surrounding context'. It leaves path, max_results, file_pattern, context_lines, and case_sensitive unexplained beyond their schema names and defaults.

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

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

The description names a specific verb and resource: it Searches Markdown documentation using a regex or text pattern. It also enumerates the return content, and the phrase 'Prefer this for finding specific topics across all documentation' distinguishes it from generic doc listing/reading 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?

It provides a clear use case: 'Prefer this for finding specific topics across all documentation.' It does not explicitly name sibling alternatives or state when not to use it, but the guidance is clear enough to route an agent to the correct tool.

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