Drupal Code Query

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld=false, and the description adds genuinely new behavioral facts: verdicts come from 'git apply --check against the tag', the service performs no downloading so URL patches must be fetched by the caller, and the caveat that 'An applies patch can still be wrong at runtime'. It stops short of describing performance bounds or how the tag is resolved beyond the failure_mode/unknown notes.

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?

Very dense and long, but the opening question front-loads the purpose and each subsequent line is scoped to either an input parameter or an output field. Some output-field lines (e.g. hunks_shipped/moved_to) are tightly packed and could be split for readability, but little is redundant filler given there is no output schema.

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 the full return-value burden and does so: it documents tag, applies_at, fuzzy, hunks_failed, reverse_applies, mr, merged_in_version, suggested verdicts, failure_mode, syntax_errors, core_references/flagged/deprecated/checked, next_step and counts. The unknown-row handling ('Report it as unclear. Never leave the row out.') closes the failure loop for an agent.

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

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

Schema description coverage is 100%, so 3 is the floor; the description goes beyond it by stating that a package's patches must be sent together and in composer.json order, and by enumerating the accepted patch sources (.drupal.org/files/issues, git.drupalcode.org MR/commit, .patch or .diff suffixes) and the accepted project/version formats. The order constraint in particular is not enforced by 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 lead sentence states a precise test with two outcomes ('does each composer patch still apply to the release... and is its fix already in that release'), which is a specific verb+resource rather than a restatement of the name. It also implicitly separates this tool from reroll_patch by naming that sibling as the escalation path for conflicts.

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?

Explicit when-to-use ('Send composer_json and composer_lock after composer update. Add patch_files for every patch'), explicit when-not ('Do not download releases. Do not run patch --dry-run'), and an explicit alternative routing rule ('conflicts: call reroll_patch with that item'). Ordering guidance per package is also 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?

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?

The description goes far beyond the readOnly/idempotent annotations: it explains filter combination, count behavior, core_minor matching semantics, unreleased-tip exclusion, transitive member_of walks, max_depth coupling, and row-level computed fields like cms_depth and member_of_count.

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, front-loaded with the core operation and followed by scoped bullet explanations. For a 10-parameter tool with nuanced membership and core-minor semantics, every sentence earns its place and no filler is present.

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

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

With no output schema, the description appropriately documents return row fields, count field, and next_offset behavior. It also covers edge cases such as projects not in any root and the absence of next_offset on the last page, making the tool fully callable.

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: core_minor's composer-constraint logic, missing as an inversion that produces the 'upgrade gap list', member_of's transitive behavior, max_depth's dependency on member_of, and the fact 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 ('List drupal.org projects') with clear scope, ordering ('largest install base first'), and paging behavior. It also distinguishes itself from single-project siblings by noting 'One project: project_profile. Its pending records: 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?

Examples of intended queries ('top modules without an 11.4 branch', 'themes over 10k installs without security coverage') make usage context clear. It points to project_profile and project_upgrade_report for one-project and pending-record cases, but does not exhaustively cover when not to use this tool versus all 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?

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?

The description goes well beyond the readOnly/idempotent annotations, documenting error behavior for unknown projects, the refusal of included sections when the bundle predates the view, data sources, exclusions like the unreleased tip, and count semantics. This gives an agent a precise model of side effects and limitations.

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

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

The description is long but organized into tight bullets that each carry specific output facts; no filler. Some definitions, such as core_constraint, are repeated between bullets, and the cross-reference line at the top adds only marginal value, so it is not perfect.

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 the full burden of explaining return shape, and it does so thoroughly: every return section, parameter effect, paging mechanism, and error/refusal case is covered. An agent has enough to invoke 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?

All six parameters are already described in the schema (100% coverage), so the baseline is 3. The description adds value by explaining how include modifies the related section, how dependents_offset paginates via next_offset, and how releases/months interact with output, so it earns a 4.

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 quoted purpose statement naming the exact questions the tool answers for one drupal.org project, then enumerates returned sections. It is a specific verb+resource and distinguishes itself from siblings by explicitly naming project_upgrade_report and list_symbol_users as related but separate concerns.

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 use when a one-project profile is needed, but it never states when to choose this over siblings or when not to use it. The cross-references to project_upgrade_report and list_symbol_users hint at boundaries without giving explicit 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 cover read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral detail beyond that: per-record verdicts, ranking order, cap refusal for limit, exclusion of test/test-support symbols, and which fields each returned entry contains. This is exactly the kind of non-obvious behavior an agent needs to predict results.

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 longer than average but dense and well-structured, with purpose front-loaded and details organized by record verdicts and removed symbols. The length is justified by the absence of an output schema and the complexity of the report, though a few phrases 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 carries the full burden of explaining return values, and it does so thoroughly: verdicts, counts, ranked evidence, per-entry fields, removed_symbols structure, and exclusion rules. An agent has enough information to call the tool and interpret its result 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 description coverage is 100%, so the schema already documents limit, project, and target_version formats and constraints. The description mostly restates those constraints and adds output semantics rather than new parameter meaning, so the baseline of 3 is appropriate.

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

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

The description opens with a concrete question the tool answers: whether a contrib project is ready for a target core version and what work remains. It also names sibling tools for narrower tasks, immediately distinguishing this aggregate readiness report from get_change_record and list_symbol_users.

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 readers to get_change_record for one record's detail and to list_symbol_users for a symbol's users, which helps agents choose between tools. It does not enumerate broader exclusion conditions or compare against other readiness-related siblings like check_patches or project_profile, so it stops short of full when-not 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, idempotent, and non-destructive. The description adds substantial behavior beyond that: one-statement constraint, no semicolon, 15-second limit, 16 KB shared byte budget, truncation handling, dev-branch isolation rules, adoption polarity, and error behavior. 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?

The description is long but every block earns its place: purpose is front-loaded, followed by invocation rules, result semantics, data-model pitfalls, and error behavior. The bulleted structure makes dense operational guidance easy to scan.

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 flexible SQL tool with no output schema, the description covers return shape, truncation, limits, error hints, required preliminary steps, domain-specific correctness rules, and external documentation caveats. An agent has enough context to invoke 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining statement limits, result truncation, byte budget, SQL syntax constraints, and when to use statements instead of sql. This goes beyond the schema's field-level 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?

States a specific verb and resource: run read-only DuckDB SELECTs over the dataset behind the other tools. It also distinguishes itself from siblings by targeting questions none of the other tools ask and by saying to prefer a typed tool when one fits.

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 directs the agent to call describe_dataset first, tells it to prefer a typed sibling when one fits, and defines the generic SQL-query use case. This gives both positive guidance and an exclusion criterion for 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral detail: it downloads nothing (so the user must fetch the patch), it merges patches from base or tags, it explains the meaning of reroll.status and reroll.verified, and it instructs the user on what not to do (e.g., 'Do not run git apply --check or patch --dry-run'). No contradiction with annotations; the description enhances transparency beyond the structured fields.

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 very long and dense, but it is well-structured with bullet points and clear sections (Input, status handling, etc.). Every sentence carries necessary operational detail—there is no fluff. However, it could be more concise by summarizing key points or moving some details to an output schema; as-is, it is verbose but justified by 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's complexity (8 parameters, multiple statuses, nested resolutions) and the absence of an output schema, the description covers every aspect: input requirements, how to interpret results, what to do for each status (clean, conflicts, syntax_errors, unavailable), and even edge cases like fuzzy patches and already-merged patches. It is complete enough that an agent can call the tool correctly without external 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 coverage is 100% (every parameter has a description). The tool description adds substantial meaning beyond the schema: for 'patch' it explains the difference between index lines and hand-made patches, for 'base' it details the merge fallback order, for 'drop_tests' it clarifies the effect on the re-roll, and for 'resolutions' it provides a detailed structure and behavior. This goes well beyond the schema's one-line descriptions, making parameters far more actionable.

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

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

The description clearly states the tool's purpose: 'Re-roll one composer patch that check_patches reported conflicts or fuzzy: a new diff that applies to the installed release.' It specifies the verb (re-roll), the resource (composer patch), and the condition (conflicts or fuzzy), distinguishing it from the sibling check_patches.

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 explicit: 'Call check_patches first for the whole list. Call this once per patch that came back conflicts or fuzzy.' It also describes when to send resolutions, what to do after each status (clean, conflicts, etc.), and even warns against manual steps like running git apply --check or editing the patch by hand. Clear when-to-use and when-not-to-use guidance is present.

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 cover the safety profile (readOnly/idempotent/non-destructive/closed-world), and the description adds substantial behavior beyond them: data freshness (bundle_date makes later releases invisible), the distinction that installed_unknown/installed_from_tag are not findings about the site, and that a plan omits scan rows and never contains a re-rolled diff.

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, but the body is a ~600-word wall of dash-prefixed fragments whose bullet semantics are ambiguous, with some cryptic lines ('the files go from disk to the api by curl'). Length is defensible given no output schema, but structure and readability suffer.

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 the full return burden and does so: it documents rows/counts/candidates, the patches items, and the plan shape (counts, package_counts, no_release, patches, applying, warnings, next_step). An agent has what it needs to interpret results 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% and the schema descriptions are already rich, so the baseline is 3. The description still adds real meaning the schema doesn't: patches:true switches the return shape to a plan, patches_lock answers alone over extra.patches and the patches file, and an empty target_core scans against the installed core.

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 precise verb+resource+scope: which drupal/* packages need a new release for a target core. It also implicitly differentiates from siblings by naming check_patches and reroll_patch as downstream steps, so an agent knows where this tool sits in the workflow.

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?

Explicit when-to-use ('send composer.lock and composer.json once'), an explicit exclusion ('do not query one package at a time'), and explicit routing to alternatives ('pass them to check_patches after composer update', 'plan.next_step points at reroll_patch'). It even states when to re-call the tool without 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 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.