Drupal Code Query

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

The annotations declare readOnlyHint=true and idempotentHint=true, but the description goes far beyond by explaining the internal mechanism: 'Verdicts come from git apply --check against the tag.' It also reveals side-effect-free operation ('This service downloads nothing'), and warning about potential runtime issues ('An applies patch can still be wrong at runtime'). It discloses the scope of checks and the meaning of fuzzy matches, all of which complement the annotations.

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

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

The description is long but well-structured with bullet points and a clear hierarchy. It front-loads the purpose and then systematically covers input, output fields, and edge cases. Every sentence carries essential information; there is no fluff. It loses one point only because its length might be off-putting, but given the tool's complexity (many output fields, re-roll logic), this length is justified.

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?

No output schema exists, so the description is the sole source of output semantics. It explains every return field: tag, applies_at, fuzzy, hunks_failed, reverse_applies, mr, merged_in_version, suggested, next_step, counts, hunks_shipped, files_shipped, moved_to, core_references, flagged, deprecated, checked. It also specifies how to handle unclear verdicts ('Report it as unclear. Never leave the row out.') and when to trigger reroll_patch. This is a complete operational guide.

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 provides descriptions for each parameter, but the tool description adds substantial meaning: it explains the exact format of items (project names, version format, patch URL types), how patch_files should be keyed ('keyed by the source as written'), and the default behavior of target_core. It also clarifies that composer_json's extra.patches becomes the item list. This is far beyond baseline schema descriptions and fully compensates for any gaps.

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

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

The description opens with a precise question: 'Does each composer patch still apply to the release the site installed, and is its fix already in that release?' This states the verb (check), resource (composer patches), and the specific evaluation criteria. It is clearly distinguished from sibling tools like scan_composer (which likely scans composer files) and project_upgrade_report (which focuses on upgrades).

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

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

The description gives explicit when-to-use and when-not-to-use instructions: 'Send composer_json and composer_lock after composer update.' It also provides negative directives: 'Do not download releases. Do not run patch --dry-run.' It explains the alternative input mode (items) and when to use it ('Leave empty to build the items from composer_json and composer_lock'). It even specifies follow-up actions like 'conflicts: call reroll_patch with that item.'

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior, and the description adds rich behavioral context: output varies by argument mode, no-args returns invariants and empty-result causes, view mode returns columns/filters/joins, and recipe mode returns ready-to-run statements. No contradictions with annotations.

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

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

The description is dense but well-structured with a leading usage directive and clear bullet-style modes. Every sentence carries useful information, and the most important instruction ('call it with no arguments first') is front-loaded.

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

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

For a read-only metadata tool with no output schema, the description covers all three invocation modes, return contents, and connection to query_dataset. It also gives enough detail about invariants and empty-result causes to set agent expectations. Nothing critical 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 100%, so the baseline is 3. The description adds extra meaning by explaining the no-arg overview, how view vs. views relate, what each variant returns, and how recipes connect to query_dataset. This goes beyond the schema descriptions without needing to compensate for missing schema docs.

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

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

The description clearly states this tool learns/describes the dataset before SQL work, and distinguishes it from query_dataset and other typed siblings. It specifies exactly what the tool does: returns an overview, view metadata, or recipes depending on arguments.

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

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

It explicitly says to call it before writing SQL for query_dataset, to call with no arguments first, and to prefer a typed tool when one answers the question. This provides clear when-to-use and when-not-to-use guidance relative to 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?

Even though readOnlyHint/idempotentHint already signal safe reads, the description adds valuable behavioral context: the flavour taxonomy, the fact that adoption counts only cover contrib development branches, the legacy/migrated meanings, the ranked-head ordering with outstanding first, and the meaning of an empty symbols list. None of this is present in annotations.

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

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

The description is well-structured: a front-loaded summary sentence, routing guidance, then concise bullets for flavour, adoption, output shape, and symbols. It is longer than minimal but every bullet earns its place. Minor deduction for the ambiguous 'do not raise top_projects' phrasing.

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

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

With no output schema, the description carries extra responsibility for explaining return semantics, and it mostly succeeds: it lists returned content, explains flavour values, adoption scope, and symbol roles. It does not describe exact JSON shape or possible error conditions, but an agent has enough to invoke the tool correctly. The ambiguity around top_projects keeps this from a 5.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that top_projects controls the ranked head and that the head is ordered outstanding first, and it connects nid to change_record_nids from what_changed. The phrase 'do not raise top_projects' is slightly cryptic, but overall the description enhances the schema.

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

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

The description opens with a specific verb and resource — 'Return one core change record in full' — and enumerates the contained fields. It also differentiates itself from siblings by pointing to list_change_records for finding records and lookup_core_symbol for a single symbol's detail.

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

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

The description gives explicit routing: use list_change_records or what_changed to find records, use lookup_core_symbol for symbol-level detail, and use project_upgrade_report for a single project's upgrade report. This gives an agent clear when-to-use and when-not-to-use guidance.

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

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

Annotations already assert readOnly, idempotent, non-destructive behavior, and the description adds significant behavioral detail beyond that: inclusive bounds, supported version forms, flavour taxonomy, exclusion of policy-only records, and the return contract (count of all records plus a ranked head with nids). This is exactly the kind of context annotations alone cannot convey.

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 front-loaded with a one-sentence summary followed by compact bullet points. Each bullet earns its place: bounds, flavours, project behavior, and return shape. There is no repetition, filler, or vague language.

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

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

With no output schema, the description supplies the essential return contract: count of every record, a ranked head, and each entry's nid for use with get_change_record. Combined with parameter semantics and explicit sibling routing, an agent has everything needed to invoke and interpret 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 coverage is 100%, so the baseline is 3, but the description adds real meaning by explaining version-form semantics, inclusive bounds, flavour values, and what the project parameter actually counts. The limit parameter is left to the schema, which already documents its default and cap.

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 first sentence names the exact operation and resource: 'List the core change records ... that target a range of core versions, tagged by flavour and ranked, with counts.' It also explicitly differentiates from what_changed (symbol-level diff) and get_change_record (single record in full), so an agent can disambiguate it from the sibling list 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?

The description explicitly routes to alternatives: 'For the symbol-level diff, use what_changed. For one record in full, use get_change_record.' It also clarifies which records never appear here (policy-only) and explains the narrowing effect of the project parameter, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already mark the tool read-only and idempotent, but the description adds important runtime behavior: development branches only, unknown targets are refused with a pointer to lookup_core_symbol, per-project capping semantics, ordering, and next_offset absence on the last page. There is no contradiction with the annotations.

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

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

The description is front-loaded with the primary purpose and an example, then moves into dense but purposeful reference details. Every sentence adds information needed to call the tool correctly; there is no filler or repetition of the title.

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

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

With no output schema, the description fully specifies the row fields, ordering, pagination behavior, and error handling. The inclusion of sibling-tool routing and parameter edge cases makes the tool self-sufficient for an agent deciding whether and how to invoke it.

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?

Although the input schema covers all parameters, the description adds meaning beyond it: the target may include or omit the leading backslash, rel_kind values are clarified, per_project controls the capping while project_edges gives the full count, and limit/offset/next_offset behavior is explained. This is substantial navigational guidance for constructing queries.

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 exactly what the tool does: lists contrib classes that extend, implement, or use a core class/interface/trait, with one row per edge including file and line, paged. The concrete example "who subclasses FormBase" and the naming of related sibling tools remove ambiguity.

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

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

It explicitly routes the agent to alternatives: call-site counts should use list_symbol_users, and symbol-status or candidate lookup should use lookup_core_symbol. It also explains the unknown-target refusal path, making the choice between tools clear.

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

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

Beyond the read-only/idempotent annotations, the description discloses ordering by install base, paging via next_offset, filter combination semantics, and the exact core_minor algorithm (newest release on each development branch, patch-level constraint matching, unreleased tip changes not seen). This is substantial behavioral detail and does not contradict the annotations.

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

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

The description is information-dense but not padded; purpose, examples, filtering semantics, and return shape are each covered in compact, organized bullets. Front-loading the core purpose and ordering makes the tool easy to understand quickly.

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

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

With no output schema, the description compensates by specifying the row fields, count, and next_offset behavior. Combined with full parameter documentation and annotations covering safety guarantees, an agent has everything it needs to call and interpret 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?

The schema already documents all parameters at 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema, especially for core_minor and missing: it explains how constraints are read, what 'missing' means for upgrade gaps, and that all filters apply to both count and rows.

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 action and resource: 'List drupal.org projects after filters' with deterministic ordering. It gives concrete example queries and even points to sibling tools for the single-project and pending-record cases, so an agent can distinguish it from project_profile and project_upgrade_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?

The examples ('top modules without an 11.4 branch', 'themes over 10k installs without security coverage') make the intended use concrete, and the note that project_profile and project_upgrade_report cover one-project and pending-record needs provides some alternative routing. It could be more explicit about when to choose query_dataset or search_code instead, but the context is clear.

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

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

Annotations already mark read-only/idempotent, and the description adds substantial behavior: paging, public-symbol-only filtering, development-branch scope, evidence rollup timestamp, ordering, and per-row fields. No contradiction with annotations.

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

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

Description is long but every sentence carries operational detail; bullet layout makes it scannable. Front-loaded with main purpose before filters/output details.

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

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

This is a complex read tool with no output schema, so the description carries the burden of defining return values; it covers count, symbol_count, symbols_matched, row ordering, row fields, symbol fields, and last-page pagination marker. Complete enough for an agent to invoke and interpret results.

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?

With schema coverage at 100%, the baseline is 3; the description adds value by explaining fqn-or-filter alternatives, filter combinations via the 13.0 example, and public-symbol restriction. It does not restate every schema description but reinforces the most consequential interactions.

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'), resource ('contrib projects'), and scope ('using one core symbol, or any symbol in a class of symbols'), with explicit output shape. Differentiates itself from lookup_core_symbol by noting that sibling answers one symbol with a head of 30.

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?

Clearly says to pass either fqn or filters, gives a concrete example query, and references sibling tools (lookup_core_symbol, subsystem_coupling) for adjacent behaviors. It could be more explicit about when list_projects is the better choice, but guidance is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds substantial behavioral detail beyond those annotations: the meaning of status flags like removed, scheduled_removal, deprecated, placeholder; the audience and usage scope; the evidence rollup timestamp; and the exact fallback behavior for unresolved fragments, including ordering and calling again with one fqn.

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 long but dense and well structured: a one-sentence purpose, sibling routing, then terse bullet-like sections for fqn forms, resolved output, and unresolved output. Every sentence carries distinct information; nothing is redundant with the schema or annotations.

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 four parameters, no output schema, and two very different response modes (resolved vs. fragment fallback), the description covers both modes, the field types returned, the sorting and caps, the fqn input forms, and the relevant sibling tools. An agent has enough to invoke the tool correctly and interpret the main output without guessing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters well. The description adds meaningful extra semantics: case-insensitive matching for fragments, public-symbols-only scope, candidates ordering ('entries starting with the fragment come first, then by projects_using'), and the top_projects cap context. This exceeds the baseline of 3.

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

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

The opening sentence states a specific verb and resource: 'Answer is this core symbol safe to use, and who still uses it for one symbol.' It also distinguishes its fragment-lookup behavior from exact symbol lookup and names sibling tools that cover related but different needs, so an agent can tell it apart from list_symbol_users, what_changed, and search_code.

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

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

The description explicitly routes to alternatives: 'Every user in pages: list_symbol_users. Changed between versions: what_changed. Code text: search_code.' It also explains when the tool switches from exact lookup to candidate listing ('A name that resolves to nothing returns the catalog entries containing it instead'), giving clear selection criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds substantial behavioral detail: unknown projects produce an error, included sections can refuse when the bundle predates the view, the unreleased tip is excluded from dev branches, and counts are drupal.org month-end installs. No contradiction with annotations exists.

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 in the first sentence, followed by dense but organized bullet sections with no filler. Though long, the length is justified by the number of output sections, parameter-dependent behaviors, and edge cases that need explanation.

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

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

Despite lacking an output schema, the description inventories all returned sections, defines core_constraint and core_minors semantics, covers error and limitation behavior, and names sibling tools for adjacent data needs. An agent can predict both call semantics and result interpretation without further documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful beyond-schema behavior for the include parameter: 'related' becomes the full report, required_by uses paging with next_offset, and 'trend' aligns series to months with null and '*' conventions. This is enough to move above baseline.

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

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

The description states a specific purpose: answer 'what is this contrib project, how big is it, which core versions does it support, what moves with it' for one drupal.org project. It clearly names the resource scope ('one drupal.org project') and points to sibling tools for adjacent concerns such as pending change records and core symbols. This makes it distinguishable from list_projects and other 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?

The description gives clear context for when to use the tool and names alternatives for adjacent data needs: 'Pending change records: project_upgrade_report. Core symbols it calls: list_symbol_users.' It also explains optional include modes and what they replace. It does not state an explicit global 'when not to use this tool' rule, but the context is strong enough for an agent to route 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?

Annotations already mark the tool read-only and idempotent; the description adds substantial behavior beyond that: how records apply, the three verdict states, that output is counts followed by a ranked head, that entries include cross-project counts and nids, and that test/test-support symbols are excluded. This is exactly the extra context agents need.

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 long but every sentence earns its place: it states purpose, routes to alternatives, then defines the output contract in dense, organized bullets. There is no filler or repetition, and the most important purpose is front-loaded.

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

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

With no output schema, the description compensates fully: it explains return shape, verdict counts, ranked outstanding records, per-entry evidence fields, nid linkage, removed_symbols structure, ordering, and exclusions. An agent has enough context to invoke the tool correctly and interpret its results.

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

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

Schema description coverage is 100%, so the input schema already fully documents project, target_version, and limit. The description does not add parameter semantics beyond that, but with complete schema coverage it does not need to; baseline 3 is appropriate.

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

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

The description opens with a specific, non-tautological purpose: answering whether a contrib project is ready for a target core version and what work remains. It also distinguishes itself from sibling tools by explicitly naming get_change_record and list_symbol_users for different granularities of detail.

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 clear routing guidance: use get_change_record for one record's detail and list_symbol_users for a symbol's users. This tells an agent when not to use project_upgrade_report and which alternatives to pick, satisfying the when/when-not requirement.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description substantially extends this with execution behavior: 15-second timeout, no statement outside the bundle, shared byte budget, truncation flag, dev-branch isolation, adoption polarity, and empty-result hints. This is far beyond what the annotations alone convey.

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 long but dense and well-structured: a front-loaded purpose sentence, then bulleted operational sections covering result format, isolation rules, polarity pitfalls, error behavior, and external resources. Every section conveys necessary constraints for correct invocation; there is no filler or repetition.

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

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

Despite having no output schema, the description explains the result shape, truncation condition, error behavior, view inventory via describe_dataset, domain-specific adoption polarity, and dev-branch filtering. This is complete enough for an agent to invoke the tool correctly on complex analytical questions.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial parameter semantics: statements limits of 5 and per-statement results/errors, max_rows cap of 500 with shared 16 KB budget, one SELECT/SHOW/DESCRIBE/FROM-first per statement, no semicolon, and LIMIT/OFFSET guidance on truncation. This meaningfully enriches the schema definitions.

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

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

The description opens with a specific verb and resource: 'Run read-only DuckDB SELECTs over the dataset behind the other tools, for a question none of them asks.' It explicitly frames the tool as a complement to the sibling tools and tells the agent to prefer a typed tool when one fits, making sibling differentiation clear.

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

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

The description gives explicit usage guidance: call describe_dataset first, prefer a typed tool when one fits, and use this tool for questions none of the other tools ask. It also details constraints such as 'no semicolon' and using statements for multiple queries, giving clear when-to-use and how-to-use 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?

The description discloses important behavior beyond annotations: the service downloads nothing, patch merging depends on index lines/base, verification semantics (reroll.verified), and exact actions for clean/conflicts/syntax_errors/unavailable states. These details complement the readOnlyHint and idempotentHint annotations without contradicting them.

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 long but front-loaded with the core purpose and organized by response statuses, making it scannable. It earns its length for a complex re-merge workflow, though a few repeated merge/apply-check notes could be tightened.

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

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

With no output schema, the description fully covers return semantics: reroll.status values, verified/verified_by, patch truncation, path conventions, and core_references. It leaves no major aspect of invocation or interpretation undocumented.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds workflow-level meaning on top: 'one patch per call', how base is used for hand-made patches, and the resolution variant shapes, which helps disambiguate cases the schema only lists structurally.

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

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

The description opens with a specific verb and resource: 'Re-roll one composer patch that check_patches reported conflicts,' and explains the operation as a 3-way merge returned as a new diff. It clearly distinguishes itself from check_patches and other siblings by naming the prerequisite tool and the per-patch scope.

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

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

It explicitly instructs to call check_patches first, call reroll_patch once per conflicting patch, and provides detailed when-to-use guidance for each reroll.status outcome. It also gives exclusions ('Do not run git apply --check or patch --dry-run') and alternative routes for truncated patches.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral detail: it explains that the server cannot read the filesystem, how the upload command works, the meaning of installed_unknown and installed_from_tag, and the limitation that releases after bundle_date are invisible. It also discloses that a plan request excludes scan rows. This exceeds what annotations alone provide.

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 long, but every sentence adds specific, non-redundant detail. It is structured into clear thematic paragraphs (parameters, row types, candidates, patches, plan) and starts with the core purpose. It is appropriately sized for the tool's complexity, though a more concise summary could be considered for strictly minimal usage.

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 nested parameters, multiple modes, and no output schema, the description must explain output behavior. It does this thoroughly: it defines row types (no_release, update, unknown, current), explains candidates and patches, describes plan output structure, and covers edge cases like dev versions and outside_drupal. 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?

Although the schema covers 100% of parameters, the description goes far beyond it. It explains how composer_lock can be either text or a path, that an empty target_core scans against installed core, and the purpose of patch_files and composer_json. It clarifies the relationship between metapackages and sub-modules, adding semantic depth that the schema alone does not convey.

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

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

The description opens with a precise, question-like statement of purpose: 'Which of a site's drupal/* packages need a new release for a target core, and which have none?' It also distinguishes itself from siblings by referencing check_patches and reroll_patch as separate steps, making the core scanning role clear.

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

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

The description explicitly instructs to send composer.lock and composer.json once, and not to query one package at a time. It also explains when to use the 'patches' mode and references check_patches for later steps, but it does not explicitly name alternatives such as project_upgrade_report or when not to use this tool. The guidance is strong but could be more explicit about 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?

Annotations already declare read-only and idempotent behavior, and the description adds substantial behavioral detail: RE2 regex limitations, .module/.install/.inc counted as PHP, no automatic language filter, result shape with total_matches/total_files, by_repo semantics, limit cap, and parse-error propagation.

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 dense but every sentence earns its place. It opens with the core purpose, then covers regex syntax, language handling, and return behavior in a structured way. No filler or redundant restatement of the tool name is present.

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

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

With no output schema, the description properly explains return values: total_matches, total_files, head of files, and by_repo rows. It also covers edge behavior like truncation, the 50-result cap, the 1000-file pull, and parse-error messages, making it sufficiently complete for correct invocation.

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

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

Although schema coverage is 100%, the description goes beyond the schema by explaining RE2's lack of lookaround/backreferences, which file extensions count as PHP for lang:/sym:, how literal mode interacts with filters, and the by_repo pull/truncation behavior. This adds real meaning to query, literal, filters, and by_repo.

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: 'Search the source of every indexed contrib project, plus core, for a code pattern.' It also distinguishes the tool from siblings by explicitly saying symbol-use counts belong to list_symbol_users or lookup_core_symbol.

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

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

The description gives explicit routing: use list_symbol_users or lookup_core_symbol for 'Who-uses-a-core-symbol counts.' It also provides practical guidance on query construction, filters, literal mode, and the absence of an applied language filter, helping the agent decide how to invoke the tool.

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

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

Beyond the read-only annotations, the description reveals important behavior: unknown subsystems are refused with nearest matches, self-edges are omitted, lift is defined, floors filter noise, and edge cases like no clearing edges or no MR file data produce notes. This gives the agent strong expectations of output and failure behavior.

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

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

The description is dense but well-structured with clear bullets. Every line adds operational detail, from accepted inputs to output fields and edge-case notes. Despite its length, there is no filler or redundancy.

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

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

With a complex 5-parameter tool and no output schema, the description still explains all modes, parameter forms, output edge fields, defaults, filtering behavior, and special-case notes. Nothing critical is left to guesswork.

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?

Although schema coverage is 100%, the description adds substantial meaning: subsystem names can be case-insensitive names or buckets like module:views, edge fields are enumerated with a precise lift formula, and the interaction of min_lift/min_co_fail with count and edges is explained. This goes well beyond the schema descriptions.

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

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

The description states a specific analytical question ('what else tends to fail when a merge request touches this core subsystem') and names the data source (CI history over about 9,000 core merge requests). It also distinguishes the two main calling modes (subsystem vs issue_nid), so the tool's purpose is unmistakable.

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

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

The description gives clear usage modes: pass subsystem, pass issue_nid, or pass nothing to list subsystems. It also explains how an unknown subsystem is handled. It does not explicitly contrast this tool with sibling alternatives, but the specialized context makes the intended use clear.

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

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

Annotations already mark readOnly, idempotent, and non-destructive, and the description adds substantial behavioral detail: inclusive bounds, bucket independence, pagination edge cases, unplaceable symbols, removal_kind semantics, and how filters affect counts. No contradictions with annotations.

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

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

The description is long but highly structured, with each bullet covering a distinct behavioral aspect of a complex 9-parameter tool. It is front-loaded with the core purpose and then organizes mode-specific details, filters, and usage constraints without significant redundancy.

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

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

For a tool with no output schema and 9 parameters, the description is exceptionally complete: it explains both output modes, row shapes, grouping rules, ranking, filtering, pagination, limits, data source, and special cases. An agent has nearly everything needed to call it correctly and interpret results.

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?

Although schema coverage is 100%, the description adds meaning well beyond the parameter descriptions: version form semantics, 'from=11.3' upgrade interpretation, flat-mode bucket requirements, limit page-size behavior, offset pagination, and when next_offset is absent. This materially improves correct parameter usage.

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 first line states exactly what the tool does: answer what changed in the core API between two versions, listing added, deprecated, and removed symbols. It also explicitly distinguishes itself from related siblings: lookup_core_symbol for a single symbol and list_change_records for human write-ups.

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

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

The description gives clear usage context: contrib development branches only, from the evidence rollup. It also names alternatives with one-symbol lookup and human write-up routes, and explains when to choose flat vs grouped mode.

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