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

No annotations are present, so the description carries the disclosure burden. It usefully states that the tool produces a paste-ready snippet and validates props. However, it does not describe behavior on invalid props, whether schemas are fetched remotely, or any other side effects.

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, no filler; the primary action and output are front-loaded, and validation behavior is appended as a secondary clause.

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 generator tool with fully-described parameters, the description is mostly complete: it identifies input, output, and validation. It lacks explicit error/validation-failure behavior, but that's a minor gap given the simple scope.

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 each parameter already has a description (blockName examples, blockId # suffix, children references). The tool description adds no parameter-specific meaning beyond that, 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?

The description names the action ('Generate'), the resource ('VTEX IO block'), and the exact output form ('JSONC snippet ... ready to paste into blocks.jsonc'). It also mentions prop validation, which separates it from scaffold/lookup 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 context is clear: use when you need a block snippet for blocks.jsonc. But there is no explicit when-not-to-use or comparison with siblings such as lookup-block-props or scaffold-vtex-app.

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

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

With no annotations, the description must carry behavioral context. It clearly frames the operation as read-only via 'Get', and the exact-ID statement makes the look-up behavior and its constraint transparent. It stops short of describing error handling or return formatting, so a perfect score is not warranted.

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 action, with examples and a routing hint. Every clause contributes value and there is no redundant elaboration.

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 documentation-lookup tool, this is complete: it defines the input, the exactness requirement, the alternative for finding IDs, and the output type ('full documentation'). No additional information is needed 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?

Schema coverage is 100%, so the parameter is already fully documented in the schema, including examples. The description adds the important exact-ID qualifier and references search-concepts, but it does not need to compensate for missing schema 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?

Description opens with a specific verb and resource ('Get full documentation for a VTEX concept'), names the exact-ID mechanism, and provides concrete examples. This clearly distinguishes it from search-concepts, which finds IDs rather than explaining them.

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

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

The description explicitly tells the agent to use search-concepts first when the exact ID is not known, which is a clear when-to-use and alternative routing instruction. This removes ambiguity about the tool's role relative to its sibling.

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

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

There are no annotations, so the description must carry the full burden of behavioral disclosure. It implies a read-only operation through the verb 'look up,' but it does not explicitly state that it is non-mutating, requires no special permissions, or has no side effects. The description does not contradict any annotations (none exist), but it leaves safety details to inference.

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

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

The description is a single, front-loaded sentence that states the action and object immediately. It includes useful examples without padding. Every word earns its place, and it avoids redundancy with 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?

For a simple lookup tool with one parameter and no output schema, the description adequately conveys the type of information returned (props, description, usage examples). It does not describe the output structure or format, but for this purpose the content is likely sufficient. A minor gap is the lack of clarification on whether the output is a JSON object or free text.

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 description coverage is 100% and the blockName parameter already includes examples in its description. The tool description adds no additional parameter semantics beyond the examples already present in the schema. It neither clarifies formatting, constraints, nor edge cases, so it stays at the 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 uses a specific verb ('Look up') and a clear resource ('props, description, and usage examples for any VTEX IO Store Framework block'), with concrete examples. This distinguishes it from sibling tools like lookup-vtex-api, which targets API endpoints rather than store framework blocks, even though that differentiation is not explicit.

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

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

No guidance is given on when to use this tool versus alternatives. The description does not mention when not to use it, nor does it reference the sibling lookup-vtex-api or other tools. An agent must infer the appropriate context from the name and examples alone, which is insufficient given the sibling set.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does disclose that the tool returns endpoints, auth details, and request/response models, which adds meaningful detail. However, it does not mention output format, whether external network access is involved, or any rate limiting or 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 a single, front-loaded sentence that states the core purpose and then provides the list of supported APIs. Every part earns its place, with 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?

For a single-parameter lookup tool with no output schema, the description adequately explains what the tool returns and the scope of APIs it supports. It could be more complete by noting the expected response format or when it should be preferred over concept/search siblings, but it is sufficient for an agent to invoke it correctly.

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

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

The schema already describes the single 'api' parameter with 100% coverage, including examples. The description mostly repeats the same API-name list, adding little semantic meaning beyond the schema. The baseline of 3 applies because the schema does the heavy lifting.

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 action ('Look up VTEX REST API reference') and the resource (VTEX REST API reference), enumerating the specific API domains covered. This makes it immediately distinguishable from sibling tools like lookup-block-props, scaffold-vtex-app, and search-concepts.

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 the tool is for looking up VTEX API reference information, but it does not explicitly say when to use this tool versus alternatives like search-concepts or explain-concept. There are no exclusions or when-not-to-use conditions, so usage guidance is only implied.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the primary behavior: generating specific files (schema.graphql and TypeScript resolver stubs). However, it does not mention whether existing files would be overwritten, where files are placed, or any other side effects, which are important for a file-generating tool.

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

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

The description is a single, well-structured sentence that front-loads the action and output. Every word earns its place, with no fluff 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?

The description covers the core output but leaves gaps: it does not specify file locations, overwrite behavior, or how this scaffold relates to the broader VTEX IO app workflow. Since there is no output schema and no annotations, these missing details prevent the description from being fully self-contained.

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 sufficiently documents all four parameters. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 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?

The description names a specific verb ('Generate'), specific resource ('GraphQL schema and resolver files'), and concrete outputs ('schema.graphql and TypeScript resolver stubs'). This clearly distinguishes it from sibling scaffolding tools like scaffold-vtex-app or scaffold-node-service by focusing on GraphQL-specific scaffolding.

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

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

The phrase 'for a VTEX IO app' provides some context, but the description never states when to choose this tool over the sibling scaffold-vtex-app or scaffold-node-service. No exclusions or alternative routing are given, so usage guidance is implied rather than explicit.

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

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

No annotations are provided, so the description carries the full burden. It says 'generate' and lists output files but does not disclose whether this overwrites existing files, requires authentication, writes to the current directory, or has other side effects. For a code-generation tool that likely creates files, this is a significant gap.

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

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

A single, information-dense sentence with no wasted words. It front-loads the core purpose and then lists the main content types, making it 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?

Given the tool's complexity (6 parameters, no annotations, no output schema), the description is underspecified. It fails to mention important operational details like destination, overwrite behavior, dependency on VTEX IO CLI, or what success looks like. Schema covers parameter syntax, but the tool's overall behavior remains incomplete.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description adds no additional parameter semantics beyond referencing 'routes and events', which are already covered in 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?

The description states a specific action ('Generate'), a specific resource ('complete Node.js service scaffold for VTEX IO'), and enumerates concrete deliverables (index.ts, service.json, clients, middleware handlers). It is clearly distinguishable from siblings like scaffold-vtex-app and scaffold-graphql.

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

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

The description implies when to use it: when a Node.js service scaffold for VTEX IO with routes and events is needed. However, it does not explicitly mention alternatives or conditions where another sibling scaffold tool would be more appropriate.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It states it generates manifest.json and folder structures, but does not mention whether it writes to the current directory, overwrites existing files, requires an empty directory, or any side effects. The absence of this information for a file-generating tool is a significant deficiency.

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

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

The description is a single, efficient sentence that front-loads the core purpose and lists the builders. It contains no filler or redundant content, though the builder list is partially redundant with the schema enum. Still, it remains concise and scannable.

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

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

The tool is a generator with no output schema and no annotations. The description fails to mention what happens after generation (e.g., return value, success message, files written), whether any prerequisites exist (e.g., being inside a VTEX project, authentication), or how to verify the result. Given its complexity and the lack of structured metadata, the description is incomplete for an agent to use it correctly without additional assumptions.

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 each parameter. The description repeats the builder list but adds no new semantic meaning beyond what the schema provides (e.g., no examples of valid combinations, no constraints on appName format beyond kebab-case). It does not compensate for any gaps because there are none, so the baseline score of 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?

The description states a specific verb ('Generate') and resource ('complete VTEX IO app scaffold') and enumerates the builders it covers. This clearly distinguishes it from siblings like scaffold-node-service and scaffold-graphql, which target narrower scopes. An agent can immediately understand what this tool does.

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 usage for creating a full app scaffold with selectable builders, but it does not explicitly state when to prefer this over the more specific siblings (e.g., 'for a node-only service use scaffold-node-service'). With multiple scaffold siblings present, the lack of explicit routing or exclusions is a notable gap.

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

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

With no annotations, the description carries the burden of behavior disclosure. It usefully notes that results are ranked and include excerpts, but it does not discuss rate limits, authorization, or edge-case behavior. Adequate but not richly transparent.

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

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

Two tight sentences: the first establishes scope and output, the second gives workflow guidance. No filler or redundant restatement.

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

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

The description covers scope, output shape, and the natural companion tool, while the schema covers parameters. It lacks caveats about result ranking behavior or potential query pitfalls, but for a simple search tool the essentials are present.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description adds no new parameter-level meaning beyond the general notion of keyword search, 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?

The description states a specific action ('search across 391 VTEX documentation files by keywords') and a distinct resource. It also positions the tool relative to explain-concept, making its purpose and boundary clear among sibling tools.

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

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

It explicitly says to use this tool 'before calling explain-concept', giving a clear workflow context. It does not enumerate when-not-to-use against other siblings like search-courses or lookup-vtex-api, so it stops short of a full 5.

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

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

No annotations are provided, so the description carries the full burden. It states that the tool 'Returns excerpts with surrounding context', which is a behavioral detail about the output. However, it does not disclose whether the operation is read-only, any authentication requirements, or limitations such as exact-match semantics. For a search tool, this is minimal but not misleading.

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

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

The description is two sentences and front-loaded with the core action and resource. The enumeration of all course IDs is somewhat long but informative and necessary to set expectations. There is no fluff or redundancy, and it is well-structured for quick scanning.

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 there is no output schema, the description should explain the return format. It mentions 'excerpts with surrounding context' but does not specify what fields are included (e.g., course name, link, relevance score). It also does not clarify search behavior (case sensitivity, partial matching). For a tool with no annotations and no output schema, the description is adequate but leaves room for ambiguity.

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 both parameters (query and courseId) are already documented in the schema with examples. The description lists the valid course IDs in the main text, which adds some value beyond the schema (which only gives generic examples). However, this is marginal; the schema already provides the parameter purposes and formats, so the description does not significantly deepen parameter understanding.

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 action ('Search for a term') and the resource ('all VTEX IO official courses'), listing the specific course IDs. This distinguishes it from the sibling search-concepts, which searches concepts, and other tools like lookup-block-props or lookup-vtex-api. The verb and resource are specific and unambiguous.

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

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

The description implies when to use the tool (searching course content) but does not explicitly state when to use it over alternatives. With a sibling search-concepts present, there is no explicit guidance on choosing between them. It does not mention exclusions or prerequisites, so the usage context is inferred rather than stated.

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