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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Validate ARIA attributes on entity' and does not state whether the operation is read-only, what permissions are needed, or what the validation process entails.

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, front-loaded sentence with no wasted words. However, it is arguably too terse for a tool with two required parameters and no annotations, leaving key context unaddressed.

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?

An output schema exists, so return values need not be described. Still, with no annotations, 0% schema coverage, and only a minimal sentence, the description is incomplete for an agent to call the tool correctly or understand its behavior.

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

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

Schema description coverage is 0% and neither parameter has a description in the schema. The phrase 'on entity' hints that entity_type and entity_id identify a target, but no details on valid entity types, formats, or examples are provided, so the description fails to compensate for the schema gap.

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 ('Validate') and resource ('ARIA attributes on entity'), making the tool's purpose clear. It does not differentiate itself from sibling accessibility tools like accessibility_axe_scan or accessibility_wcag_check, which prevents a 5.

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?

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or context. The agent must infer usage entirely from the name.

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 behavioral burden, yet it discloses nothing about whether the scan is read-only, how long it takes, rate limits, authentication needs, or how it handles unreachable/authenticated pages. Only the operation itself is stated.

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?

A single front-loaded sentence with no filler. It is efficiently sized, though the terseness borders on under-specification rather than tightness.

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?

An output schema exists, so return values need not be explained, but with 3 parameters at 0% coverage, no annotations, and no usage context, the definition leaves too much unspecified for an agent to call it 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 the description must compensate. It mentions only the url input; the 'rules' filter and 'format' output parameters are undocumented in both the schema and the description, leaving an agent unable to reason about how to scope or format the scan.

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

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

States a specific verb and resource: run an axe-core accessibility scan on a URL. Naming the axe-core engine gives some implicit differentiation from siblings like accessibility_wcag_check and accessibility_aria_validate, but the description never explicitly contrasts itself with them.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. An agent cannot tell from the text why it would pick axe-core over accessibility_wcag_check or accessibility_aria_validate for a given task.

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, and it does disclose a meaningful trait: it is pure arithmetic that deliberately does not touch the site and works without Drush configured. This tells the agent the operation is side-effect-free and environment-independent. It does not, however, describe whether any network or auth is ever involved beyond that, so it stops short of full coverage.

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, front-loaded with the core action, and no filler. The second sentence earns its place by explaining the offline nature. It could arguably be condensed but nothing is wasted.

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?

An output schema exists, so return values need not be explained, and the behavioral note covers the key operational trait. The notable gap is color-format guidance for the two required inputs, which is needed to invoke the tool correctly. Adequate but with a clear, actionable omission.

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

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

Schema description coverage is 0% and there are two required parameters, so the description must compensate but does not. It never states the accepted color format (hex, rgb, named) for foreground/background, which is exactly the ambiguity the schema leaves open. The parameter names are self-explanatory, but format guidance is missing.

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

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

States a specific verb and resource ('Check color contrast ratio'), which is unambiguous and clearly distinct from its sibling scanning tools (axe_scan, wcag_check, aria_validate). The behavioral note 'does not touch the site' implicitly separates it from site-scanning siblings, though no sibling is named explicitly.

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?

There is no explicit when-to-use guidance, no prerequisites, and no named alternatives among the accessibility_* siblings. The usage is only inferable from the tool's purpose; an agent gets no routing signal for choosing this over accessibility_wcag_check.

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 and falls short: it does not disclose that the tool fetches/scans the given URLs, that it writes a report artifact to disk (implicit in the output_dir/output schema), whether it requires network access, or how failures are handled. Only the generic word "Generate" hints at a mutation.

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?

A single short sentence is front-loaded and waste-free, but its brevity is under-specification rather than genuine conciseness. There is little structure to organize the missing 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?

An output schema exists, so return values need not be explained here, but for a mutation tool with zero annotations and 0% parameter coverage the description leaves too much unspecified (what gets scanned, where output lands, what level controls). It is not adequate for the tool's 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 description coverage is 0% for three parameters, so the description must compensate and does not. It says nothing about the URL list, the meaning of the "level" enum-like default ("AA" WCAG conformance), or the output_dir destination.

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

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

States a specific verb+resource ("Generate ... accessibility report"), so an agent knows the operation. However, it does not distinguish itself from the closely related siblings accessibility_axe_scan, accessibility_wcag_check, accessibility_color_contrast, and accessibility_aria_validate. The word "comprehensive" weakly hints at aggregation but never says so.

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?

There is no when-to-use guidance, no conditions, and no mention of the alternative scan/check tools. An agent receiving this alongside four narrower accessibility siblings has no stated rule for choosing this report generator over them.

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 behavioral burden. 'Check' weakly implies a read-only operation, but it discloses nothing about permissions required, whether results are cached, or what a compliance result contains, leaving a mutation/read ambiguity unresolved.

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?

A single short sentence with no waste is structurally clean, but this brevity is largely under-specification rather than genuine conciseness, so it only meets the minimum viable bar.

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?

An output schema exists so return values need not be described, but with zero annotations and zero parameter documentation the description leaves too much implicit for a compliance-check tool spanning three undocumented inputs.

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 no parameter is enums, so the description must compensate, yet it explains none of entity_type, entity_id, or level. The level parameter's default of 'AA' (a WCAG conformance level) is a natural thing to document and is ignored.

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

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

States a specific verb ('check') and resource ('WCAG compliance') scoped to 'entity content'. This is clearer than the name alone, but it never distinguishes itself from the very similar accessibility_axe_scan, accessibility_color_contrast, or accessibility_aria_validate 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?

There is no when-to-use guidance, no prerequisites, and no mention of when a sibling such as accessibility_axe_scan or accessibility_report_generate would be a better choice. The agent must infer usage entirely from the name.

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 behavioral burden. Deployment is a high-impact, likely state-changing operation, but the description omits authentication requirements, permissions, destructive effects, timeout/wait behavior, and rollback context. It only discloses the underlying command mechanisms.

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, front-loaded sentences with no filler. The first states the action and target; the second states supported command paths. Every sentence is relevant.

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?

An output schema exists, so return values need not be explained. But for a 7-parameter deployment tool with no annotations and no schema parameter descriptions, the definition is missing essential context: authentication, environment targeting, branch/code path meaning, timeout/wait tradeoffs, and risk profile. It is not complete enough for safe 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 0% across 7 parameters, so the description must compensate, but it names none of them. It does not explain environment, branch, site_id, code_path, timeout, database_name, or wait_for_completion. The description adds no parameter semantics beyond what the bare schema property names provide.

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: deploy to Acquia Cloud. It distinguishes the mechanism by naming acquia-cli and Drush acquia integration. It does not explicitly differentiate from siblings, but no obvious sibling deploy tool exists.

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 one useful preference: acquia-cli is preferred over legacy Drush acquia commands. However, it does not say when to use this tool versus alternatives or what prerequisites are needed. Usage guidance is therefore implied rather than 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?

No annotations are provided, so the description carries the full burden. It hints at an external AI call ('using AI'), implying possible latency or cost, but never states whether the operation is read-only, what it returns, whether it requires credentials, or any rate 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?

A single front-loaded sentence with zero filler. It is efficient, though its brevity reflects under-specification rather than disciplined concision.

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?

An output schema exists, so return values need not be explained, but with no annotations, 0% parameter documentation, and an undefined notion of 'quality', the description is too thin for an agent to invoke this tool confidently or distinguish it from its 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?

Schema description coverage is 0% and the single parameter 'content' is undocumented in both schema and description. The description does not clarify whether 'content' is raw HTML, plain text, a node ID, or a rendered body, leaving a real ambiguity unresolved.

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

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

States a clear verb+resource ('Analyze content quality'), so the general operation is identifiable. However, it gives no differentiation from the near-identical sibling 'analyze_content_quality', and 'quality' itself is left undefined (SEO? readability? grammar?), so the agent cannot tell exactly what is being assessed.

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 when-to-use guidance, no prerequisites, and no mention of the sibling 'analyze_content_quality' which appears to do the same thing. The agent is left to guess which of the two quality tools to call.

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 of behavioral disclosure. It states nothing about whether this is read-only or mutating, whether it writes files or config, whether it requires an AI/provider backend, cost or rate limits, or determinism. For a zero-annotation AI generation tool this is a complete gap.

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 sentence with no waste, but it is under-specified rather than concise. Brevity here reflects the absence of content, not efficient structure.

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?

An output schema exists, so return values need not be explained, but everything else is missing: parameter meaning, AI-backend dependency, mutation side effects, and routing among dozens of migration siblings. Inadequate for a 2-param generation 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 description coverage is 0%, so the description must compensate. It mentions neither source_type nor target_version, gives no allowed values for source_type (e.g., D7 vs D9), and does not explain that target_version defaults to '10'. Both parameters are left semantically empty.

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 migration plan using AI' largely restates the tool name 'ai_generate_migration_plan'. It says what is produced (a migration plan) but not what it plans from or to, and does not distinguish it from related siblings like generate_migration_yaml, generate_module_migration, or map_fields_ai.

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 when-to-use guidance, no prerequisites, no alternatives named. The vast migration family (analyze_d7_site, map_modules_d7_to_d10, generate_migration_yaml, run_migration_test, validate_migration) makes sibling differentiation essential, and none is provided.

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 behavioral burden and fails: it does not disclose that the operation is read-only/advisory, that it is non-deterministic or incurs model cost/latency, or whether suggestions are persisted. 'Using AI' is the only behavioral hint and it is too thin.

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?

A single short sentence with no padding, so it is not verbose, but it is under-specified rather than genuinely concise. It is front-loaded with the action, which is the only structural merit.

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?

An output schema exists so return values need not be described, but the description omits any behavioral or parameter context for a 2-required-parameter AI tool with zero annotation coverage. An agent would be guessing at how to 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?

Both parameters (source_fields, target_bundle) have 0% schema description coverage, and the description adds nothing about their format, expected values, or relationship. 'target_bundle' in particular is opaque without documentation.

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 verb+resource pair ('Suggest field mappings') states the basic action, but 'using AI' is filler rather than scope. It does not distinguish this tool from the sibling map_fields_ai, nor does it say what kind of mappings (Drupal field config? migration mappings?) are suggested.

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?

There is no when-to-use guidance, no prerequisite (e.g., a migration or content model must exist first), and no mention of alternatives such as map_fields_ai. The agent must infer everything about invocation 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?

With no annotations, the description carries the full behavioral burden, and it discloses almost nothing. 'Using AI' faintly implies nondeterministic, network-dependent output, but there is no mention of permissions, rate limits, latency, or whether the source content is modified.

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 single sentence is short and front-loaded, but its brevity comes from under-specification rather than economy. Nothing meaningful is packed into 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?

An output schema exists, so return values need not be explained, but the description leaves the three input parameters entirely undocumented, gives no usage context, and no behavioral disclosure for a no-annotation tool. It is not sufficient for an agent to call this correctly without opening 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% for all three parameters (content, source_lang, target_lang), and the description adds no semantics whatsoever — not the accepted language code format, not the default behavior of source_lang, not whether target_lang is an ISO code or locale.

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 verb (translate) and a resource (content), so the basic action is inferable, but 'content' is vague and nothing distinguishes it from siblings like translation_add, interface_translation_add, or config_translation_add that also deal with translation.

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?

There is no when-to-use guidance at all: no indication of when AI translation is preferable to translation_add or interface_translation_add, no prerequisites, and no exclusions. The agent must guess from the name alone.

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 behavioral burden but delivers almost nothing beyond the verb. It does not say whether analysis is read-only or persists results, what 'quality' dimensions are measured, whether it is expensive/AI-rate-limited, or what triggers it. Only the read/write profile is implied, not stated.

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?

A single efficient sentence that front-loads the action and resource with no wasted words. It is appropriately sized, though the brevity contributes to the coverage gaps noted elsewhere.

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?

An output schema exists, so return-value explanation is not required, but for an unannotated AI-analysis tool the description is thin: nothing on what 'quality' means, cost, or side effects. Given the presence of a near-duplicate sibling, the definition should do more to make the tool safely selectable.

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 mutual exclusivity of node_ids and content_type and the 50-node cap are already documented in the schema. The description's 'specific nodes or an entire type' merely restates that, adding no new syntax or constraint detail. 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?

States a specific verb+resource ('Analyze content quality with AI') and the scope ('specific nodes or an entire type'), so an agent can understand the operation. However, it does not differentiate itself from the near-identically named sibling 'ai_analyze_content_quality', leaving the two indistinguishable by name.

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 only paraphrases the schema's two targeting modes ('specific nodes or an entire type') with no guidance on when to prefer this tool, when not to, or how it relates to the sibling ai_analyze_content_quality. No prerequisites, cost, or rate-limit context is given.

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 behavioral burden. It does not say whether the analysis is read-only, whether it requires the 'auth' credentials to reach a live site, whether it mutates anything, or how long/heavy the scan is. For an analysis tool hitting a remote site, that is a substantial gap.

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?

A single front-loaded sentence with no filler, which is structurally clean. However, one sentence is undersized for a 4-parameter tool with no annotations and no schema descriptions, so terseness here reads as under-specification rather than efficiency.

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?

An output schema exists, so return values need not be described, but the definition still omits authentication requirements, the meaning of the include_* toggles, and any differentiation from analyze_d9_site. An agent cannot invoke this correctly on scope alone.

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% across 4 parameters, and the description compensates for none of them. It never mentions 'auth' (an opaque anyOf object), 'site_url', or the 'include_content'/'include_modules' toggles that materially change the scan scope.

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

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

States a specific verb ('Analyze'), a specific resource ('Drupal 7 site'), and the goal ('D10 upgrade readiness'). The 'D7' qualifier does implicitly distinguish it from sibling analyze_d9_site, but the description never names that sibling or otherwise routes between them.

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 when-to-use guidance, no prerequisites, and no mention of related siblings such as analyze_d9_site, map_modules_d7_to_d10, or find_deprecated_code that an agent would need to choose between. The agent must infer the workflow position entirely.

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, and it delivers almost none: nothing about whether the analysis is read-only, what credentials 'auth' requires, how deep or slow the scan is, or whether it contacts the live site. Only the output topic (deprecated code and APIs) is stated.

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?

A single front-loaded sentence with no filler, which is appropriately sized for a short description. It is efficient rather than padded, though its brevity contributes to the missing guidance elsewhere.

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 tool with three parameters, a required site URL, and no annotations, the description omits authentication requirements, the meaning of check_deprecated, and any scan scope or safety context. The output schema does relieve it of explaining return values, but the invocation-side gaps remain substantial.

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% for all three parameters. The description implies site_url and loosely gestures at deprecated-code checking, but leaves 'auth' and 'check_deprecated' (and the fact that deprecation checking is toggleable and on by default) entirely undocumented, so it fails to compensate for the schema gap.

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

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

States a specific verb (Analyze) plus resource (Drupal 9+ site) and names the target of analysis (deprecated code and APIs). The '9+' version scope implicitly separates it from analyze_d7_site, but it does not distinguish itself from closer siblings like find_deprecated_code or deprecation_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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as find_deprecated_code, deprecation_scan, or analyze_d7_site. The only usable signal is the implied 'Drupal 9+' version filter, which is thin for routing among many overlapping analysis 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?

With no annotations, the description carries the full burden. It usefully discloses two behaviors: authentication is required to avoid under-reporting hidden JSON:API fields, and counts may optionally be persisted to a plan (i.e., it can mutate state). It says nothing about rate limits, permissions, or TLS handling despite a verify_tls parameter.

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?

Front-loaded purpose followed by a focused authentication caveat; only two sentences and no filler. The backtick-heavy formatting is slightly awkward but does not impede reading.

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 covers return values, but a 7-parameter tool with zero schema descriptions and no annotations needs more explanatory coverage than this. Key inputs (token vs username/password relationship, source_url, verify_tls, migration_id, resource_type) are left entirely to inference.

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 all 7 parameters are undocumented in structured form. The description only clarifies the semantics of username/password; token, source_url, verify_tls, migration_id, and resource_type remain unexplained, so it fails to compensate for the coverage gap.

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

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

States a specific verb ('Analyze') and resource ('source Drupal JSON:API resource type'), plus the secondary effect of storing counts in a plan. It is distinguishable from D7/D9 site analyzers by naming JSON:API resource types, but does not explicitly contrast with the many other inventory/analysis 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?

There is no explicit when-to-use guidance or alternative routing among siblings like analyze_d7_site, analyze_d9_site, or jsonapi_resource_types. The authentication note hints at a scenario (unauthenticated analysis under-reports) but never frames it as a usage condition.

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 full behavioral burden. It implies a mutation operation but says nothing about required permissions, idempotency, whether the role must already exist, or side effects on existing roles.

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 front-loaded sentence with no wasted words. Its brevity is appropriate in form, though it is under-specified for the tool's complexity.

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 two required parameters, no annotations, and 0% schema description coverage, the description is far too sparse. While an output schema exists (so return values needn't be explained), the description should still cover parameter formats, prerequisites, and behavioral traits.

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 adds no meaning beyond the parameter names. It does not clarify whether 'uid' is a numeric ID or username, or whether 'role' expects a machine name or label.

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 ('Assign a role to a user'), making the operation clear. However, it does not distinguish this tool from sibling tools like remove_role, get_user_roles, or list_roles, which an agent could confuse it with.

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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The description merely restates the action without any contextual routing.

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

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

With no annotations, the description carries the full burden and does so: it declares read-only behavior ('composer outdated'), states environmental requirements, documents the require-dev filtering workaround and why it exists, and explains the cross-referencing against composer audit. That is unusually rich operational context.

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?

Front-loaded with the core purpose, then prerequisites, then the two flags. Well organized, though the parenthetical justifications ('because composer marks none of them itself') add minor length without changing behavior.

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?

An output schema exists, so return structure needn't be described, and the description still notes that advisories are attached when security_only is set. For a two-flag read tool, nothing an agent needs to call it correctly is missing.

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 0%, so the description must compensate and it does: include_dev is explained as the switch that un-excludes dev dependencies (resolved via require-dev), and security_only is explained as intersecting the outdated list with composer audit advisories and attaching them. Both params gain meaning absent from 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?

States a specific verb and resource ('List packages with newer versions available, from composer') and scopes it clearly against sibling tools like composer_audit and composer_update. An agent can identify exactly what this returns without opening the 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?

Gives explicit prerequisites (composer.json, network access), explains both flags' effects, and names the alternative path: 'The composer_audit tool lists advisories regardless of updates.' When-to-use versus when-to-use-the-other is spelled out.

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 disclosure burden, yet it says nothing about where the backup is written, whether an existing backup is overwritten, required permissions, or how long the operation takes. 'Via Drush' is a mechanism hint but not behavioral context.

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?

A single six-word sentence, front-loaded and waste-free. Its brevity is disciplined, though the terseness borders on under-specification rather than true 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?

An output schema exists so return values need not be described, but the tool has no annotations and an undocumented parameter, and the description omits prerequisites and behavioral details an agent needs 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?

The single parameter backup_path has 0% schema description coverage and is never mentioned in the description, so the agent has no explanation of what it controls (presumably the output location) or the meaning of the null default. The description adds nothing beyond the name.

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

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

States a specific verb (create), resource (database backup), and mechanism (via Drush), which is enough for an agent to distinguish it from other maintenance tools like cache_rebuild or drush_command. It doesn't explicitly contrast itself with any sibling, but the purpose is 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?

No guidance on when to use this versus other maintenance or Drush tools, and no prerequisites (e.g., does it need a running site, sufficient disk, specific permissions). The description only says what it does, leaving the agent to infer 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 provided, so the description carries the full behavioral burden. It confirms a write operation but says nothing about required permissions, side effects, or what happens to existing blocks; one sentence cannot cover this for a mutation tool.

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

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

Four words with no wasted words, but the brevity reflects under-specification rather than efficient conciseness; there is nothing to earn its place beyond naming the action.

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?

An output schema exists, so return values need not be explained, but a 6-param mutation tool with 0% schema coverage and no annotations needs far more than a four-word description to be invocable correctly.

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

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

Schema description coverage is 0% across 6 parameters (id, label, plugin, region, settings, visibility). The description adds no meaning for any of them, leaving required fields like plugin and label unexplained.

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

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

States a specific verb+resource ('Create a new block'), so the basic action is clear, but it does not distinguish block_create from siblings like block_place or block_update, nor does it explain what a 'block' is in this Drupal context.

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 on when to use this vs alternatives such as block_place, block_update, or layout_builder_section_add, and no prerequisites or context are offered.

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 of behavioral disclosure. 'Delete' implies a destructive mutation, but nothing is said about permissions required, whether the block is removed permanently or merely disabled/unplaced, or what side effects occur to existing placements.

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?

A single front-loaded sentence with zero filler. It is efficient, though its brevity borders on under-specification rather than true 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?

For a destructive tool with no annotations and an undocumented identifier parameter, the description is far too thin. An output schema exists so return values need not be explained, but the agent still lacks irreversibility, permission, and scope information needed to call this safely.

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 single required parameter block_id has no documentation in the schema. The description does not add meaning either - it never explains whether block_id is a numeric ID, machine name, or UUID, or where to obtain it.

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

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

States a specific verb (delete) and resource (block), which cleanly separates it from siblings like block_get, block_list, block_create, and block_update. It does not name siblings explicitly, but the verb+resource pair is 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?

No guidance on when to use this versus alternatives, no prerequisites, and no warning that this is a destructive, likely irreversible operation. The agent must infer all of that from the verb alone.

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 supplies essentially none. It does not state what happens when the ID is missing or invalid, whether the block must be placed/enabled to be returned, or what permissions are needed.

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?

It is a single front-loaded sentence with no filler, which is efficient, but its terseness tips into under-specification for a tool with two parameters and no annotations. There is no wasted text, but also no earned 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?

An output schema exists, so return-value explanation is not required, but the definition is still incomplete: the 'include' parameter is undocumented and behavior around missing IDs or permissions is absent. For a two-param tool with no annotations, this leaves meaningful 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?

Schema description coverage is 0%, so the description must compensate. 'By ID' gives some meaning to block_id, but the 'include' parameter is entirely unexplained in both the schema and the description, leaving critical behavior undocumented.

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?

Names a specific verb ('Get') and resource ('a single block'), with the singular scope distinguishing it implicitly from block_list. However, it does not explicitly name or contrast with sibling tools such as block_list or layout_builder_get, so the differentiation is left to inference.

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 when-to-use guidance, no prerequisites, and no mention of alternatives for retrieving block data. An agent must guess whether this is the right retrieval tool versus block_list.

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 does not disclose pagination behavior (default page_limit 50, page_offset 0), filtering support, whether the list is scoped to a context (e.g., current theme or region), or what the response contains. 'List all blocks' is behaviorally opaque for a tool with three parameters.

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, front-loaded sentence with no wasted words. Its brevity, however, comes from omission rather than efficiency, so it earns a 4 for structure but not a 5.

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 an output schema, so return-value explanation is not required. But with no annotations, three undocumented parameters, and a crowded sibling set, the description is far too thin. It fails to provide the context an agent needs to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate for three undocumented parameters. It mentions none of them: 'filters' is a generic anyOf object, and page_limit/page_offset are undocumented. The description adds no parameter meaning whatsoever.

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 ('List all blocks'), so the purpose is identifiable. However, it provides no differentiation from siblings like block_plugin_list, block_region_list, or block_get, which all deal with blocks in Drupal. An agent cannot tell from this text which block-related tool to pick.

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?

There is no guidance on when to use this tool versus the numerous block-related siblings. No prerequisites or conditions are stated. The description merely says it lists blocks, leaving the agent to infer usage.

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 behavioral burden. It does not say whether placement requires specific permissions, whether it is idempotent, what happens to an existing block already in that region, or how weight affects ordering — only a bare statement of action.

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?

A single front-loaded sentence with no wasted words, which is structurally clean. But for a three-parameter mutation tool it is undersized to the point of under-specification rather than genuine 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?

An output schema exists so return values need not be explained, but with zero annotations and zero parameter documentation the description is not complete enough for an agent to invoke a mutating block operation 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 the description must compensate. It names 'region' and 'weight' but adds no meaning (e.g., that weight is a delta/ordering value where lower sorts first) and never mentions 'block_id' at all, leaving the key required parameter undefined.

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

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

States a specific verb ('Place') and resource ('block') plus a scoping context ('in a region'). However, it does not distinguish this from the many sibling block tools (block_create, block_update, block_get, block_region_list), so an agent cannot tell whether 'place' means create, assign, or reorder a block.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as block_create or block_update. The agent is left to infer the scenario entirely from the name.

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 behavioral burden and does almost nothing with it. It implies a read-only enumeration but never confirms that, nor does it explain pagination behavior (default page_limit 50) or that results may be truncated.

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?

A single short sentence with no padding, so it is structurally clean and front-loaded. But it is terse to the point of under-specification rather than genuinely concise, leaving obvious questions unanswered.

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?

An output schema exists, so return values need not be explained, but the two undocumented input parameters and the absent annotation coverage leave real gaps. Nothing tells the agent how to filter, how results are paged, or how this differs from block_list.

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% for two parameters. The `filters` parameter is an opaque free-form object with additionalProperties true, and the description gives no syntax, supported keys, or examples; page_limit is only self-documenting via its default. The description adds nothing to compensate.

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

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

States a specific verb and resource ('List available block plugins'), which reads clearly against neighbors like block_list (placed blocks) and block_region_list (regions). However, it never names or explicitly distinguishes itself from those siblings, so the agent must infer the difference between a block plugin definition and a placed block.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as block_get or block_list. The agent is left to guess whether to call this before block_create/block_place or instead of block_list.

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. The word 'List' implies a read operation, but the description does not disclose the crucial behavior of what happens when theme is null (presumably defaults to the active theme), nor anything about the shape or limitations of the listing.

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?

A single tight sentence with no filler, and the core action is front-loaded. It is arguably under-specified rather than bloated, so conciseness itself is fine.

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-optional-parameter tool with an output schema present (so return values needn't be described), the description is nearly adequate. The remaining gap is the null/omitted-theme behavior, which an agent genuinely needs to 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?

Schema description coverage is 0% and the single parameter has a default of null, so the description should clarify the parameter. 'for a theme' echoes the parameter name and gives light context, but it never explains the null default or what theme to pass, leaving the most important semantic detail undocumented.

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 (List) and resource (regions for a theme), which is clearer than the bare name. However, it does nothing to distinguish this from nearby siblings like block_plugin_list, theme_region_create, or layout_builder_sections_list, so an agent must infer the boundary on its own.

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?

There is no indication of when to use this tool versus alternatives, no prerequisites, and no mention of what the optional theme argument does when omitted. The agent gets a purpose but no routing 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure for a mutation tool. Beyond the word 'Update', it says nothing about partial versus full updates, permissions required, side effects, reversibility, or what happens to omitted fields. This is a severe gap for an update operation.

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 extremely short, but it suffers from under-specification rather than conciseness. A single three-word fragment does not front-load useful information or earn its place by clarifying the tool's behavior.

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 five-parameter mutation tool with no annotations and no schema parameter descriptions, the description is completely inadequate. Although an output schema exists and need not be explained, the input side and behavioral expectations are left entirely to inference.

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% across five parameters (block_id, label, region, settings, visibility), and the description adds no parameter meaning at all. An agent cannot tell from the description what any argument does or how the nested settings and visibility objects should be shaped.

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 and resource ('Update a block'), so the basic action is identifiable. However, it provides no detail about what a block is in this context, which block types or fields are involved, or how it differs from siblings like block_create, block_delete, or layout_builder_update. The purpose is minimally viable but not specific.

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?

There is no guidance on when to use this tool versus alternatives such as block_create, block_delete, block_get, or block_place. The description supplies no context, prerequisites, or exclusions to help an agent choose correctly.

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 states no behavioral traits: whether the block is reversible, whether it requires permissions, what happens to active sessions, or whether it affects content authored by the user. A single tautological sentence adds nothing.

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 short sentence, front-loaded and free of waste. However, it is under-specified rather than concise; brevity here comes at the cost of information.

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

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

For a mutation tool with no annotations, 0% parameter documentation, and a rich sibling set, the description is inadequate. Even with an output schema, the agent lacks guidance on effect, permissions, and reversibility.

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 single parameter 'uid' is undocumented in both schema and description. The description doesn't identify the uid as a user identifier or its expected format, leaving the agent to infer it from the tool name.

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

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

States a clear verb (Block) and resource (user account). It distinguishes itself from unblock_user by its action, though it doesn't explicitly mention that sibling. Minimal but specific enough to convey intent.

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 when-to-use guidance. Given the sibling unblock_user and the user management set (create_user, delete_user, update_user), the description offers no indication of prerequisites or relationship to these 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 behavioral burden. It helpfully discloses the mechanism (drush pathauto:generate) and warns that the required 'pattern' parameter is a no-op, but it never states whether regenerating overwrites or deletes existing aliases, what permissions are needed, or whether the operation is reversible.

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 purpose is front-loaded, which is good. But the second paragraph spends a full sentence on historical trivia ('The previous implementation ran drush uuri, which is not a Drush command') that does not help an agent select or invoke the tool, diluting an otherwise short description.

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?

An output schema exists, so return values need not be described. For a mutation tool with no annotations, though, the description leaves key operational facts uncovered: the meaning of 'action', and the effect on existing aliases when they are regenerated.

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% across three parameters, so the description must compensate. It explains 'pattern' (not applied) and loosely implies 'bundle' ('for a content type'), but 'action' — which has a default of 'generate' and presumably other values — is never explained, leaving the agent guessing at valid inputs.

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 opening sentence states a specific verb, resource, and scope: 'Regenerate URL aliases for a content type.' That is clear on its own, but it gives no differentiation from the sibling 'pathauto_generate', which the description itself says this tool invokes ('runs drush pathauto:generate'). An agent cannot tell from the text why it should pick this over that 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 clarifies that 'pattern is not applied here' and routes pattern management to pathauto_pattern_create / pathauto_pattern_update, which is useful scope guidance. However, it never says when to use this tool versus pathauto_generate, so the primary when-to-use decision is left 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 full burden. It does convey blast radius ('every node matching a set of filters'), which is useful, but a bulk write tool should disclose reversibility, whether updates merge or overwrite existing field values, transaction semantics, and permission requirements — none of which appear.

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?

A single front-loaded sentence with no waste, and the scoping condition is stated plainly. It is efficient, though its brevity contributes to the behavioral gaps noted elsewhere.

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?

An output schema exists, so return values need not be explained, and all three params are schema-documented. However, for a bulk mutation with zero annotations, the description omits the safety and semantic context an agent needs to call it responsibly.

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 already documents all three parameters; baseline 3 is appropriate. The description adds no syntax or format detail (e.g. filter operators, expected update value shape) beyond what the schema provides.

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

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

States a specific verb (apply), resource (nodes), and scope (every node matching a set of filters), which clearly separates it from the single-record update_node sibling. It does not name the alternative explicitly, but the 'bulk' framing and filter-based selection make the intent 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?

No guidance on when to use this versus update_node or query_nodes, and no prerequisites stated. There is no warning about the irreversible, wide-blast-radius nature of a bulk mutation, leaving the agent to infer usage conditions.

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 supplied, so the description carries the full burden. It implies invalidation via 'clear' but says nothing about whether the action is destructive or reversible, what permissions are required, or what happens when the optional bins argument is omitted (default null) – a materially ambiguous outcome for a cache tool.

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?

A single front-loaded sentence with no filler, but its brevity reflects under-specification rather than tight communication. It is efficient but leaves key operational details unstated.

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 mutating cache operation with no annotations and an ambiguous optional parameter, this is too thin. Although an output schema exists to explain returns, the description still omits destructive/permision context and the behavior when no bins are 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 0% for the single 'bins' parameter. The description only echoes the parameter name and adds no format, allowed bin names, or default-omission behavior, so it does not compensate for the undocumented 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?

States a specific verb (Clear) and resource (cache bins), so the agent knows the operation. It does not, however, distinguish itself from the closely-named sibling cache_rebuild or explain what a 'bin' is, leaving the agent to infer the difference.

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 when-to-use guidance, no preconditions, and no mention of the alternative cache_rebuild. The sentence implies only that clearing is possible, not when an agent should prefer it over a full rebuild.

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 does disclose real behavioral facts beyond the title: the scope ('all caches'), the two-phase nature (clear then rebuild, so nothing is permanently destroyed), and the Drush execution path. It says nothing about performance impact, site availability during rebuild, or required permissions, which for a full-cache operation is a notable omission.

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?

A single front-loaded sentence that states the action, its scope, and its execution mechanism with no filler. Nothing needs trimming or reordering.

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?

An output schema exists, so return values need not be described, and with zero parameters the schema burden is minimal. However, for a broad cache operation with no annotations, the description omits impact/availability considerations and any routing relative to cache_clear, leaving meaningful 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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading parameter claims are made.

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?

Names a specific verb and resource ('Clear and rebuild all Drupal caches') and adds mechanism ('via Drush'), so the action is unambiguous. It does not differentiate itself from the very similar sibling cache_clear, so it stops short of a 5.

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?

There is no when-to-use guidance and no reference to alternatives, even though cache_clear sits right beside it in the tool list and is the obvious confusion point. The agent is left to guess whether rebuilding is warranted versus simply clearing.

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 usefully discloses that AI is involved and that deletions require confirm=True, but leaves ambiguous what 'cleaning' actually does (merge, delete, normalize?), what data is destroyed, whether it is reversible, and what permissions are needed.

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 front-loaded sentences with no filler; the purpose comes first and the safety gate second. It is perhaps too terse for a destructive AI operation, but not padded.

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 destructive, AI-driven mutation tool with no annotations and no output schema, the description is sparse. It omits what the operation returns, how duplication/malformation is detected, whether changes are logged or reversible, and what happens when confirm is omitted or false.

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% for the required entity_type and bundle parameters, so the description must compensate. It only explains confirm=True and says nothing about the semantics or expected values of entity_type and bundle.

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

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

States a specific verb ('Clean'), resource ('duplicate or malformed nodes'), and mechanism ('using AI'), which distinguishes it from generic node CRUD siblings like delete_node or update_node. It does not explicitly name an alternative, but the purpose is unambiguous.

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

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

The description gives no guidance on when to choose this tool over delete_node, update_node, or analyze_content_quality, nor any prerequisites or exclusions. Only the confirm requirement is mentioned, which is an operational detail rather than usage routing.

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

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

With no annotations, the description carries the full behavioral burden. It does not say whether PHPStan must be installed/configured, whether the run is read-only, how long it takes, or how issues are surfaced. Only the implied 'analysis' framing hints at a non-destructive read.

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?

A single front-loaded sentence with no filler. It is efficiently worded, though its brevity here shades into under-specification rather than pure tightness.

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?

An output schema exists, so return values needn't be described. However, with no annotations, 0% schema description coverage, and no usage guidance, the definition is too thin for a three-parameter analysis tool whose siblings are numerous and easily confused.

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 compensates for none of the three parameters. The meaning and valid range of 'level' (default 5, presumably 0-9), the format of 'configuration', and the expected shape of 'path' are all left unexplained.

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

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

States a specific verb and resource ('Run PHPStan static analysis') and scopes it to 'Drupal custom modules'. An agent knows what the tool does, but nothing distinguishes it from closely related siblings like code_sniffer, deprecation_scan, or code_quality_report.

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?

There is no when-to-use guidance and no mention of alternatives, despite a crowded field of code-quality siblings. The agent must infer that this applies to PHP analysis versus Twig (theme_lint_twig), deprecations (deprecation_scan), or sniffing (code_sniffer).

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 does disclose useful behavior: directories nest as children, files report a size, and the tree is depth- and item-capped to bound the response. That truncation disclosure is genuinely valuable, but there is no mention of permissions, error behavior for a missing module, or how the caps are applied.

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, front-loaded with the core purpose, then behavior, then bounding. No wasted prose.

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?

An output schema exists, so return values need not be described, and the capping behavior is covered. The remaining gap is the single undocumented parameter, which is the one thing an agent must supply correctly to call this 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?

One parameter ('module') with 0% schema coverage, so the description must compensate and largely does not. Saying 'a local module's directory structure' hints that 'module' is the module of interest, but it never clarifies the expected format (machine name vs. path) or scope.

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

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

States a specific verb and resource: 'Show a local module's directory structure as a nested tree.' The scope (local module) is clear and the output shape is named. However, it does not distinguish itself from the many codebase_* siblings such as codebase_paths_list or codebase_files_list, which touch similar territory.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. An agent choosing between this, codebase_files_list, and codebase_paths_list gets no routing help from the description.

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 present, the description carries the full burden and does well: it discloses the 64 KB truncation limit and the accompanying truncated flag, plus the security rejections (absolute paths, '..' traversal, symlinks escaping the codebase). It does not describe behavior on a missing file, permission failures, or encoding handling, which keeps it short of a 5.

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, front-loaded with the operation, then the path convention, then the guardrails. Every sentence earns its place with no filler.

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

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

An output schema exists, so return-value explanation is rightly omitted, and the description covers the two non-obvious traits an agent needs (truncation and path safety). The `module` parameter and error behavior remain unaddressed, so it is not fully complete for a two-required-param 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 0%, so the description must compensate. It defines `path` clearly (module-relative, with an example) but says nothing about the `module` parameter beyond the phrase 'from a local module', leaving half the parameters undocumented in both schema and description. Partial compensation only.

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

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

States a specific verb and resource with scope: 'Read one file from a local module.' The word 'one file' plus 'path is module-relative' implicitly separates it from listing tools such as codebase_files_list and from codebase_function_read, but no sibling is named explicitly, so the differentiation is inferential rather than 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?

Usage is implied by the module-relative path convention and the 'local module' scoping, but there is no explicit guidance on when to pick this over codebase_search, codebase_files_list, or codebase_function_read, and no stated preconditions. Adequate context, no routing help.

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 behavioral burden. It discloses the scope (every file, module-relative paths), which is useful. However, it doesn't state whether the list is recursive, whether results are cached, pagination behavior, or what happens with invalid modules. Adequate but with gaps.

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, front-loaded purpose followed by the practical use case. Every sentence earns its place with no waste.

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

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

Has an output schema, so return-value explanation is not required. But with 0% schema coverage on the module parameter and no annotations, the definition leaves key ambiguities (module identifier format, recursion depth) unresolved.

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 single 'module' parameter is completely undocumented in both schema and description. The description doesn't clarify what format the module identifier takes (machine name, path, etc.), leaving a real ambiguity for the agent.

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

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

States a specific verb+resource (list every file in a module) with the output format (module-relative paths). It distinguishes itself from siblings like codebase_paths_list and codebase_module_list by being file-level within a module, but doesn't explicitly name alternatives, so it falls short of a 5.

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 states the use case: find the right path before calling codebase_file_read or codebase_function_read. This is clear upstream context, though it doesn't mention when NOT to use it or name sibling alternatives like codebase_search or codebase_paths_list.

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 usefully discloses search behavior ("Searches all PHP-ish files in the module, including class methods") and that it returns path/line/code, but says nothing about what happens when the function is not found or when multiple matches exist, and auth or size limits are unaddressed.

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 with zero padding; the core action is front-loaded and the scoping benefit follows immediately. Every sentence carries 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?

An output schema exists, so explaining return values is not strictly required (though it does). With no annotations and 0% parameter coverage, gaps remain around edge cases and parameter formats for a lookup tool that can plausibly match zero or several functions.

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 and largely does not. It only implies that "module" identifies the module and "function_name" the function; it adds no format details (machine name vs. path, namespacing, qualified method names) needed to supply these values correctly.

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

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

States a specific verb ("Extract") and resource ("single PHP function (with its docblock) from a module"), and explicitly scopes it against reading whole files. An agent can tell it apart from codebase_file_read or codebase_hooks_find without opening another 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?

Implies when to use it ("enough to review one hook or method without reading whole files"), giving clear context and a soft contrast against whole-file reading. It stops short of naming an explicit alternative tool or stating 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 does disclose the useful behavioral detail that the hook prefix is optional and that results are grouped per module with file/line, which is real context. It stops short of stating whether this is a read-only inventory across all enabled modules or how large result sets behave.

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, front-loaded with the outcome and followed by the input-format note. No wasted clauses, though the line-wrap breaks interrupt an otherwise tight statement.

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?

An output schema exists, so return-shape detail is not required, and the description covers purpose plus the single input nuance. It omits any scope caveat (e.g., enabled vs. all modules) and any alternative, leaving a small but real 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?

Schema description coverage is 0% for the single hook_name parameter, so the description must compensate, and it does: it explicitly says the hook may be supplied with or without the 'hook_' prefix, which is the one non-obvious input fact. One-parameter tools anchor this near the 4 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?

States a specific verb (Find) and a precisely-scoped resource: local modules that implement a given hook, returning file and line. That scope is clearly distinguishable from siblings like codebase_function_read or module_hook_implement.

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 this tool applies (you want to locate hook implementations), but it names no alternative and gives no when-not guidance. A sibling like module_hook_implement could plausibly overlap, and the reader gets no routing help.

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 disclosure burden. It does reveal the state effect (a local index rebuild that other codebase tools depend on) and the return contents, but says nothing about cost, runtime, idempotency, or what happens to the prior index. Adequate but with clear gaps for a mutation-style operation.

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, zero filler, and the core action is front-loaded. The trigger condition is stated immediately after the action, which is the right order for an agent scanning for relevance.

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 local reindex, the description covers purpose, trigger, and return shape. Because an output schema exists, the return-value sentence is mildly redundant but not harmful. The only substantive omission is the lack of any cost or safety context, which is acceptable for this benign operation.

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 declares zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter detail is needed or missing.

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

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

States a specific verb and resource: 'Rebuild the local codebase module index.' This clearly separates it from read-oriented codebase siblings like codebase_search or codebase_module_list, which merely consume the index. It stops short of naming a specific sibling it is not, so it is differentiated by implication rather than explicitly.

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?

Gives an explicit trigger condition: call it after installing, enabling or creating modules. This tells the agent when the tool is needed and why. There is no when-not guidance or named alternative, so it does not reach the top band.

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 supplied, so the description carries the full burden. It does disclose the shape of the payload heavily, and 'Describe' makes the read-only nature evident, but it says nothing about failure modes (unknown/non-local module), index staleness, or whether a refresh is needed first.

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, zero filler, with the core action front-loaded and the return contents listed immediately after. The trailing 'everything the index knows about it' is a mild restatement but costs almost nothing.

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?

An output schema exists, so return values did not need spelling out, and the description covers them anyway. Remaining gaps are the undocumented module identifier and the unstated dependency on an up-to-date codebase index, which matters for a tool that reads solely from an index.

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 single required 'module' parameter has no description in either place. 'one local module' hints at scope but not the expected format (machine name vs. path vs. human label), so an agent must guess the identifier convention.

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

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

States a specific verb ('Describe') plus resource ('one local module') and enumerates exactly what comes back (info.yml fields, dependencies, reverse dependencies, hooks, services, routes, classes, file count). It implicitly separates itself from list-style siblings like codebase_module_list, but never names a sibling explicitly to sharpen the boundary.

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 'one local module in full' implies the use case (deep inspection of a single indexed module rather than a listing), but there is no explicit when-to-use, no prerequisites (e.g. requiring a fresh codebase index), and no named alternative such as codebase_hooks_find or codebase_search for narrower lookups.

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, and it does add real behavioral detail the schema cannot convey: the exact field set of each item and the precise semantics of the unused flag ('nothing references it and it implements no hooks'). It stops short of disclosing scope of the underlying index, pagination, or whether results are cached.

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 that are front-loaded with the core purpose and free of filler; the field enumeration is dense but earns its space by telling the agent what it will receive. Minor cost is that the field list reads as a catalog rather than prioritized 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?

An output schema exists, so return values need no explanation, and for a two-parameter read tool the description is close to adequate. The gap is that with zero annotations and zero schema coverage, the 'scope' parameter and the meaning of 'indexed' (against which snapshot/index) remain undefined, which matters for calling the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It explains show_unused well, including the two-part condition for flagging, but the 'scope' parameter (default 'all') is never mentioned and its allowed values are left entirely to the agent's guess.

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

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

States a specific verb ('List') and resource ('indexed local modules with metadata'), and enumerates the returned fields, so the agent knows exactly what surface it exposes. It does not, however, distinguish itself from close siblings like codebase_module_describe, inventory_modules, or codebase_unused_modules, so an agent cannot route purely from the text.

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?

There is no explicit when-to-use or when-not guidance and no named alternatives among the many codebase_* siblings. The only usage signal is implicit: 'With show_unused=True' hints at a conditional read for finding orphaned modules, which is suggestive but not a routing rule.

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, and it does communicate a meaningful behavioral trait: the set of directories that are actually indexed (modules, web/modules, sites/*/modules, core), which is a common source of false confidence in search coverage. It is a read-only, zero-param introspection tool, so there is little else to disclose.

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 tight sentences: the first states what is returned, the second states why to call it. Front-loaded and free of 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?

An output schema exists, so return values need not be enumerated; the description covers purpose, usage intent, and the scan-location semantics that determine how the result should be interpreted. Nothing an agent needs to call this correctly is missing.

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, which is the defined baseline of 4. The description adds no parameter detail, but none 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 gives a specific verb and resource ('Show the configured docroot and the module directories indexed'), which is concrete and distinguishable from search/index siblings like codebase_search or codebase_module_list. It stops short of naming a sibling to contrast against, but the purpose is 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?

It states a clear condition for use: verify which locations the codebase tools scan 'before relying on search results.' That is actionable context. It does not name an alternative or an explicit when-not-to-use case, keeping it just below the top band.

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 usefully discloses that it searches an index and returns closest modules plus a recommendation, but says nothing about read-only nature, whether the index must be refreshed first (codebase_index_refresh exists), or how results are ranked.

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 tight sentences with the core purpose front-loaded and no filler. Structure is good; it simply stops short of routing or constraint detail that could have earned the fifth point.

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?

An output schema exists, so return-value explanation is unnecessary, and the description covers purpose and the shape of the output. The main gap is the undocumented query parameter and the unmentioned dependency on an up-to-date index.

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?

One undocumented parameter at 0% schema coverage. The description implies 'query' is the capability being sought, which gives minimal semantic grounding, but offers no format guidance (natural language vs. keywords) to compensate for the schema gap.

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

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

States a specific verb+resource: it checks whether the local codebase already covers a capability and reports the closest existing modules with a recommendation. This is meaningfully distinct from the generic codebase_search sibling, though the description never names that sibling to make the distinction explicit.

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?

Usage is only implied by the phrase 'extend what exists rather than duplicating it,' which suggests running this before writing new modules. There is no explicit when-to-use, no when-not-to-use, and no named alternative among the many codebase_* siblings.

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, and it does disclose a genuinely useful behavioral trait: the ranking order (machine-name/name > description > code-body). It does not state read-only nature explicitly, though the output schema relieves it of explaining return values.

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?

Purpose is front-loaded in the first sentence and the ranking rule and scope note follow compactly with no filler. Well sized for the amount of information conveyed.

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 presence of an output schema means return values need not be described, and the ranking plus scope notes cover the core behavior. Still missing is any routing guidance against the many overlapping search/list siblings, leaving an agent to guess between this and module_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 coverage is 0%, so the description must compensate. It explains the meaning of scope values ('custom'/'contrib' filter by origin, 'all' includes core), which the schema does not since there is no enum. Query and limit remain undocumented, so compensation is only partial.

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

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

States a specific verb (search) and resource (local codebase) and narrows the target to 'modules providing a capability,' which separates it from list-style siblings like codebase_module_list. However, it never explicitly contrasts itself with module_search or search_entities, so the agent must infer the 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 only guidance is about the scope parameter values ('custom'/'contrib'/'all'), which is parameter semantics rather than when-to-use. There is no statement of when to prefer this over module_search, codebase_module_list, or codebase_hooks_find despite many plausible alternatives in the sibling set.

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, and it does disclose the actual heuristics used to classify a module as used rather than just asserting 'unused', which is the behavior an agent most needs to trust the output. It still omits whether results derive from a pre-built codebase index (a sibling, codebase_index_refresh, suggests staleness is possible), so it is 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?

Three short sentences, front-loaded with the definition and followed by the precise criteria that qualify a module, ending with the actionable framing 'Candidates for removal.' No filler, and the ordering matches how an agent would evaluate the result.

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 analysis tool with an output schema already covering return shape, the description supplies the classification semantics needed to interpret results correctly. The one gap worth noting is the absence of any mention of index freshness or prerequisites, which would matter for trusting a stale-codebase result.

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 there is nothing for the description to disambiguate; baseline 4 applies. The description adds no parameter detail because none 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?

States a specific verb (List) and resource (custom/contrib modules) and then operationalizes the key term by defining exactly what makes a module 'used' (dependency, service injection, hook implementation). This crisply separates it in spirit from near-neighbors like codebase_redundancy_check and module_dependencies_analyze, though it never names an alternative, so it stops short of the full 5.

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 classification rules and the trailing phrase 'Candidates for removal' imply the intent (find dead modules before cleanup/removal), which is genuine implied-usage guidance. However, it never states when to reach for this instead of dependency_scan, module_dependencies_analyze, or codebase_redundancy_check, so an agent must infer the 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?

No annotations are provided, so the description carries the full burden: it does not say whether this is read-only, which tools run by default when 'tools' is null, whether those tools must be installed/available, or how long a multi-tool run takes. For a tool that shells out to several external analyzers, that is a significant disclosure gap.

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 short sentence with the action front-loaded and zero filler. It is efficient, though the brevity edges toward under-specification rather than economy.

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?

An output schema exists, so return format need not be described. But for a multi-tool aggregator with two undocumented parameters and no annotations, the description omits the default tool set, path scope, and execution prerequisites — the agent cannot predict what will actually run.

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% for two parameters. The description implies the 'tools' parameter concept ('multiple code quality tools') but never states allowed tool names, the default when null, or whether 'path' is a module, directory, or file path. It adds almost no meaning beyond the bare schema keys.

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

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

States a specific verb+resource ('Run ... tools and generate combined report'), and the word 'multiple'/'combined' implicitly distinguishes it from single-tool siblings such as code_audit_phpstan and code_sniffer. However, it never names those siblings or enumerates which tools are aggregated, so an agent must infer the boundary from the adjective alone.

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?

There is no explicit when-to-use guidance, no named alternatives, and no condition that selects this aggregator over code_audit_phpstan / code_sniffer / code_sniffer / deprecation_scan. The only signal is the implicit 'combined report' contrast, which the agent has to construct itself.

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 and does a lot: no install prerequisite, Drupal-aware false-positive suppression (EntityQuery, stream wrappers, escapeshellarg), default exclusions of contrib/core, and the specific caveat that counts cover the full run even when max_findings truncates the list. It omits permission/auth requirements and any runtime cost, keeping it from a 5.

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?

Front-loaded with the core action, then scoping, then category enumeration, then return/truncation behavior. Every sentence carries information, though the description is on the dense side and the category list could be trimmed against the schema in principle.

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?

An output schema exists, so return-shape explanation isn't required, yet the description still tells the agent findings carry file, line, snippet, and a fix recommendation, and warns about max_findings truncation. Combined with full parameter and scope coverage, only auth/permissions context is missing.

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 — and it does for all five parameters: path is 'relative to DRUPAL_ROOT', module is a machine name, categories lists the exact registry keys, severity narrows to one level, and max_findings is tied to the truncation caveat. No parameter is left undocumented.

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

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

States a specific verb ('scan') and resource ('custom code') with the exact pattern classes covered (XSS, SQL injection, command injection, path traversal, hardcoded secrets, access-control, CSRF, deprecated-API). It also names the sibling it pairs with ('the counterpart of security_scan, which needs PHPStan installed'), so an agent can pick it apart from security_scan/security_audit without opening a 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?

Explicitly routes against the alternative: security_scan requires PHPStan, this one requires nothing installed. It also spells out the default scope when no path or module is given (site's own modules/ and themes/, contrib and core excluded). It stops short of naming security_audit/config_security_check as further alternatives, so not 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 burden. It does not say what output looks like, whether it is read-only, whether it can modify files (e.g., auto-fix), what the severity threshold governs, or whether the path is a file or directory. 'Run' is the only behavioral cue.

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?

A single eight-word sentence, front-loaded with the verb and tool. No filler or redundancy. Under-specification, not verbosity, is the issue.

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?

Although an output schema exists (so return values needn't be described), the definition is silent on behavioral profile, parameter meaning, and differentiation from the many adjacent code-quality siblings. For a tool with 0% schema coverage and no annotations, this is significantly under-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?

Schema description coverage is 0%, so the description must compensate for three undocumented parameters. It only vaguely implies the 'standard' parameter via 'Drupal coding standards', leaving path semantics (file vs directory), severity meaning, and accepted standard values completely unexplained.

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?

Names a specific tool (PHP_CodeSniffer) and the Drupal standard, which is a concrete verb-resource pairing. However, it doesn't distinguish itself from the many sibling static-analysis tools such as code_audit_phpstan, code_quality_report, deprecation_scan, or security_audit. An agent cannot tell from the description alone why it would choose code_sniffer over those.

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?

There is no statement of when to use this tool versus the auditor siblings. No mention of what kinds of findings it surfaces, when it is appropriate, or what prerequisites exist. The agent must infer usage entirely.

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 behavioral burden. It does disclose the actual state transition (published), which is the most important trait, but says nothing about required permissions, idempotency, whether the change is reversible, or side effects like notifications.

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