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

The description valuably reconciles with readOnlyHint=true by stating the tool returns the files "for the caller to write" rather than mutating the filesystem itself — that is exactly the clarification an agent needs. It also discloses the adminhtml-specific extras. It does not say what happens when target files already exist (idempotentHint implies regeneration, but the overwrite behavior is unstated).

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

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

Two sentences, front-loaded with the verb and the full artifact list, followed by the critical return-value note. No filler; every clause carries information an agent needs.

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

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

An output schema exists, so return structure need not be described, and the schema is fully documented. What is missing is prerequisite context (module existence, overwrite behavior on re-invocation) that matters for a scaffolding tool with 10 parameters.

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

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

Schema description coverage is 100% and every parameter carries its own description and defaults, so the schema does the heavy lifting. The description adds a little context — GET yields a layout handle, POST yields JSON, adminhtml adds ACL — but nothing beyond what the schema already says. Baseline 3 applies.

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

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

Specific verb ("Generate") plus an enumerated set of artifacts: routes.xml, action controller, layout handle/template, ADMIN_RESOURCE and acl.xml. It clearly scopes the frontend vs adminhtml outputs, so an agent knows exactly what will be produced. It stops short of differentiating itself from siblings like scaffold-module or add-plugin, which is the only thing keeping it from a 5.

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

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

Usage is only implied by the artifact list; there is no explicit "use this when…" or "do not use this if…" and no mention of the prerequisite that the module must already exist (scaffold-module). The GET/POST and area distinctions are useful signals but they are parameter semantics, not usage routing.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true; the description reinforces this by stating 'Returns the file for the caller to write', which tells the agent the tool does not touch the filesystem itself — a genuinely useful clarification. It also mentions the whitelist and setup:upgrade follow-up steps, adding procedural context. It stops short of saying whether an existing table definition would be overwritten, which is why it is not a 5.

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

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

A single dense sentence front-loads the verb and the artifact, with the return-value caveat appended last. Every clause carries information, though 'declarative schema etc/db_schema.xml table' reads slightly awkwardly.

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 11 parameters at 82% coverage, full annotation coverage, and an output schema, the description only needs to establish intent and the non-writing contract — both of which it does. Nothing an agent needs to invoke the tool correctly is missing, aside from optional context on existing-table handling.

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 82%, so the parameters are already well documented in the input schema. The description enumerates the element groups (columns, primaryKey, unique, foreignKeys, indexes), which mirrors the schema rather than adding semantics such as merge behavior or validation rules for these structures. Baseline 3 is appropriate.

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

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

States a specific verb (Generate) and a very specific resource (etc/db_schema.xml table) with the exact contents enumerated: columns, primary key, unique constraints, foreign keys, indexes. It is clearly distinguishable from siblings such as add-plugin or add-observer by the artifact alone, though it never names a sibling explicitly.

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

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

Usage is only implied — an agent can infer this is for adding a table to a Magento module, and the phrase 'adapted from the official declarative schema docs' hints at the authority behind the output. There is no explicit when-to-use, no conditions under which it should not be used (e.g. altering an existing table), and no named alternative.

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 meaningful context beyond them: it produces files and returns them "for the caller to write," so the agent knows no disk mutation occurs here, and notes the output is adapted from official docs.

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

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

Three short sentences, front-loaded with what is generated, followed by the return behavior and the use case. No redundant 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?

An output schema exists and the description correctly notes it returns files for the caller to write, so return values need no elaboration. The one gap is that it doesn't clarify the relationship to plugin-based interception or when an observer is preferable.

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 enum for area, the module format, and observer naming are fully documented in the schema. The description only echoes the global/per-area distinction, meeting the baseline rather than adding syntax or format detail.

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

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

The description uses a specific verb-plus-resource: "Generate an observer class and its events.xml subscription (global or per area)." It distinguishes itself from siblings like add-plugin and add-controller by naming exactly what artifacts are produced.

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

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

"Use it to react to a dispatched event" gives a when-to-use condition, but the description doesn't contrast this tool with alternatives such as add-plugin for intercepting behavior or add-controller for routing. Implied usage, no 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?

The line 'Returns the files for the caller to write' is genuinely valuable: it explains why readOnlyHint=true is consistent with a scaffolding tool and tells the agent it must perform the write itself. What remains unstated is what happens when a target file already exists, whether directories are created, and what error conditions look like.

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

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

Two sentences with zero padding; the artifact produced is front-loaded and the caller's responsibility (writing the files) follows immediately. Nothing is repeated from the 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 an output schema present and full parameter documentation, the description needn't explain return values, and the 'returns files for the caller to write' note covers the key contract gap. Minor omissions: no mention of overwrite/conflict behavior for a generator that may target existing plugin files.

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

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

Schema description coverage is 100% and every parameter (area, type, method, module, basePath, pluginName, pluginClass, sortOrder, targetClass) is documented with defaults and examples in the schema itself. The description only restates the before/after/around enum and the 'public method' constraint, adding no syntax or default guidance beyond the structured fields. Baseline 3 applies.

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

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

States a concrete verb and artifact: 'Generate a before, after or around plugin class and its di.xml declaration' for a public method of a class or interface. That resource is clearly distinct from the sibling scaffolders (add-observer, add-controller, add-db-schema), so an agent can pick it 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?

'Use it to change the behavior of a core or third-party method without rewriting the class' gives a clear positive condition for selection, and the 'without rewriting the class' clause implicitly contrasts it with a class rewrite. It stops short of naming when not to use it (e.g., event-driven changes should go to add-observer instead) or any prerequisite such as the module already existing.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value by stating what the answer contains: purpose, location (folder and area), XSD URN, and documentation pages — which the annotations 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?

Two sentences, with the purpose and scope front-loaded before the usage hint. The file-type list is long but each item earns its place by disambiguating scope; there is no filler.

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

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

For a single-parameter read-only lookup tool with no output schema, the description is nearly sufficient because it enumerates the expected return content. It stops short of saying what happens for an unrecognized file name or whether the answer is version-specific, but nothing essential to invoking it 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% and the schema's own example list already covers path forms like 'etc/adminhtml/system.xml' and 'view/frontend/layout/...'. The description's parallel enumeration reinforces that both bare names and module-relative paths are accepted, marginally improving on the schema but not adding format rules.

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?

Specific verb ('Explain') plus specific resource (Adobe Commerce module config file), with an enumerated list of file types that makes the scope unambiguous. It is clearly distinct from sibling tools like search-docs, read-doc, and scaffold-module.

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

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

The final sentence gives an explicit trigger: 'Use it before creating or editing one of these files,' which cleanly positions it relative to scaffold-module and add-db-schema. It does not name an alternative for when an agent already knows the file or wants raw doc content (read-doc/search-docs), leaving that inference to the agent.

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, idempotent, non-destructive and closed-world, so safety needs no restating. The description adds real context: results come from the official CLI reference and the input can be fuzzy ('full names, Symfony shortcuts, keywords'), which explains why near-miss queries still resolve. It omits what happens on a no-match query, a minor gap.

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

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

Two tight sentences: the first defines scope, source and return content; the second gives the call-to-action. No filler, and the core definition leads.

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 one parameter, no output schema and full annotation coverage, this is nearly self-sufficient — it even says what fields the response contains. Only the behavior on an unresolvable command name is left unstated.

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 single `command` parameter already documents full names, Symfony shortcuts and examples. The description echoes the same accepted input forms (s:up, keywords) so it adds emphasis but no new semantics beyond the schema. 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?

Names a specific verb and resource ('look up a bin/magento command') and enumerates what is returned: description, usage, arguments, options, from the official CLI reference. The bin/magento domain implicitly separates it from lookup-webapi and search-docs, though no sibling is named explicitly.

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

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

Gives a clear usage rule — 'Use it before suggesting or running a bin/magento command' — which tells the agent when to reach for it. It does not state when to prefer search-docs or read-doc instead, so alternatives remain inferred.

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, idempotent, closed-world behavior, and the description adds real context: the data comes from the official OpenAPI schema and results include path, method, parameters, body, accepted tokens, GraphQL arguments, return type and examples. It does not discuss result limits or ambiguity handling beyond what the schema's 'limit' field implies.

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

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

Two sentences, front-loaded with the resource being looked up and followed by the usage cue. Dense but each clause carries useful content; the long parenthetical listings are slightly heavy but not wasteful.

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 enumerating what REST and GraphQL lookups return, which is enough for an agent to trust the result shape. It stops short of covering keyword-search behavior or pagination beyond the schema's 'limit' field.

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% with enums for 'api' and 'method' and examples for 'query'. The description restates the accepted query forms (GraphQL name, REST path, keywords) but adds no syntax or constraints beyond what the schema already documents.

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 (look up) and precise resource (Adobe Commerce REST endpoints and GraphQL queries/mutations), plus what is returned for each. This clearly separates it from siblings like search-docs or lookup-cli-command.

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

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

"Use it when writing integrations or storefront calls" gives a concrete usage context. It does not name an alternative tool or state when-not to use it (e.g., versus search-docs), so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the docs are 'bundled' (local, not a live fetch), and a single section can be targeted instead of the whole page. It does not mention output format or how very large pages are handled.

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

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

Two sentences, front-loaded with the core action and immediately followed by the routing condition. No redundant restatement of the title or wasted clauses.

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 two-parameter, fully documented, annotation-rich read tool this is nearly sufficient; the main omissions are what the returned content looks like (markdown? full text?) and any size or truncation behavior for long pages. Since no output schema exists, that omission is a real, if minor, gap.

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

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

Schema description coverage is 100%, and the schema already documents every accepted ref form, the #anchor convention, and the section parameter with an example. The description restates the same reference types without adding syntax, precedence, or fallback behavior, so baseline 3 applies.

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

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

States a specific verb and resource ('Read a full page, or one section, of the bundled Adobe Commerce documentation') and explicitly bounds the accepted reference forms (id, source path, public URL). This is clearly distinguishable from siblings like search-docs or lookup-webapi, which retrieve different artifacts.

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

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

Gives explicit sequencing guidance: 'Use it after search-docs, or when the user pastes a docs link', which names the primary alternative and the condition that selects this tool. It stops short of any when-not-to-use statement (e.g. don't use for searching unknown topics), so it is clear context without full 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?

Discloses the single behavior an agent most needs and cannot infer: the tool returns file paths and contents and never writes to disk, so the caller must persist them. This is consistent with readOnlyHint=true/destructiveHint=false and complements rather than repeats the annotations. 'Adapted from the official docs' also signals output fidelity.

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

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

Three sentences, front-loaded with what gets generated, then the critical return/no-write behavior, then the usage cue. Every sentence carries distinct information; nothing is padding.

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

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

With an output schema covering the returned files, full parameter coverage, and annotations covering safety, the description is nearly complete. The one gap is collision behavior — it does not say what happens if files already exist at basePath, which matters despite idempotentHint=true.

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 every parameter including defaults and examples is already documented in structured data. The description adds no new parameter semantics beyond restating the Vendor_Module format, so the baseline 3 applies.

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

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

States a specific verb and enumerates the concrete artifacts generated (registration.php, etc/module.xml, composer.json) for a new Vendor_Module. 'Use it when starting a module' separates it in spirit from the add-* siblings that extend existing modules, but no sibling is named explicitly, so it stops short of a 5.

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

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

'Use it when starting a module' gives clear context for selecting it, and 'for a new Adobe Commerce module' implies the boundary against add-plugin/add-observer. There is no explicit when-not or named alternative, so it is clear context without 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restating. The description adds genuinely new context: the corpus is bundled offline (so no network freshness or live-doc assumptions), results are excerpts carrying title, public URL and source path, and read-doc is the drill-down path. It doesn't discuss ranking or relevance behavior, which is the only meaningful gap.

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

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

Three compact sentences in a clear order: what it searches, when to use it, what comes back and what to do next. The topic enumeration is dense but every item is a real retrieval cue; nothing is filler.

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

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

With no output schema, the description correctly compensates by saying results are excerpts with title, URL and source path, plus the read-doc follow-up, which is what an agent needs to chain calls. Only minor omissions remain, such as result ordering or whether excerpts are truncated.

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 query, area, and limit are already fully documented with examples, enum meanings and the default/max. The description's recital of the four doc areas roughly mirrors the area enum without adding format or query-syntax guidance beyond the schema. Baseline 3 is appropriate when the schema carries the load.

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

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

States a specific verb (Search) and a precisely scoped resource: the official Adobe Commerce/Magento developer documentation bundled offline, broken down into PHP extensions, frontend core, Web APIs and operations. It also names read-doc as the follow-up tool, so an agent can separate it from siblings like lookup-webapi or lookup-cli-command without opening a schema.

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

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

"Use it first for any 'how do I' question" is an explicit routing directive that prioritizes this tool over siblings, and the enumerated topic list (modules, plugins, DI, events, declarative schema, layouts, caching, indexers, queues, configuration) gives concrete triggers. It stops short of saying when to prefer lookup-webapi or lookup-cli-command instead, so the exclusions are implied rather than stated.

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