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

Annotations already indicate destructiveHint=true; description elaborates on overwriting files, single-call semantics, no preview, internal --force flag, and archive mechanism for safety. 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 very long and includes extensive guidance, preconditions, and presentation notes. While well-structured, it sacrifices conciseness for completeness, which may overwhelm an AI agent.

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 (destructive, multiple dependencies, dashboard-specific behavior), the description thoroughly covers preconditions, file side effects, error handling, output URL, and AI usage guidelines. No output schema, but return values are described in presentation guidance.

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 good parameter descriptions. Description adds contextual value (e.g., name prefix requirement, database type defaults) beyond the schema, though not exhaustive for all parameters.

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 clearly states the tool generates a multi-widget dashboard endpoint module from a payload spec. It distinguishes from sibling CRUD tool by emphasizing different payload shapes and artefacts.

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?

Extensive 'USE WHEN' and 'DO NOT USE FOR' sections explicitly list when to use this tool vs alternatives like codegen_create_endpoint, codegen_validate_payload, etc. Cross-references other tools.

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

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

Annotations already indicate destructiveHint true, but the description adds critical behavioral details: always executes with no preview, internal --force=true, archive mechanism for safety, and AI responsibility to confirm intent. 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?

Well-structured with clear sections, but somewhat verbose. Every sentence adds value, but the PRESENTATION GUIDANCE could be shorter. Front-loaded with key actions.

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 complex tool with 8 parameters, no output schema, and destructive behavior, the description covers behavior, safety, prerequisites, and post-invocation guidance. Completely equips the agent to use it correctly.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds context such as URL pattern, auto-lowercasing, naming conventions, and reserved name lists, but these partially overlap with schema descriptions. Still adds meaningful extra guidance beyond 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 clearly states it generates a project and endpoint module by wrapping the CLI, producing files in multiple directories. It distinguishes itself from siblings like codegen_generate_payload and codegen_validate_payload by listing DO NOT USE FOR scenarios with explicit alternative 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?

Provides explicit USE WHEN and DO NOT USE FOR sections, detailing specific user intents and mapping them to this tool vs. alternatives. Covers common Indonesian phrases and specific actions like regenerating endpoints.

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 indicate readOnlyHint and idempotentHint. Description adds that it performs live introspection, requires preconditions (restforgejs installed, config file), and describes failure modes (table not found). No contradiction.

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?

Well-structured with headings (USE WHEN, DO NOT USE FOR, Preconditions, PRESENTATION GUIDANCE). However, it is slightly verbose with repeated 'out of scope' statements. Still front-loaded with key purpose.

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

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

No output schema, but description explains returned fields (columns, PK, FK, indexes), dialect-specific types, and usage guidance for JOINs. Covers preconditions, failure modes, and presentation advice. Complete for a tool of this complexity.

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

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

Schema has 100% description coverage for all 5 parameters. Description adds meaning by explaining table name format, defaults for includeForeignKeys and includeIndexes, and config file default.

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 it describes a single database table with columns, primary key, foreign keys, and indexes. It distinguishes from siblings like codegen_list_tables (listing all tables) and codegen_validate_payload (validating payloads).

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?

Provides explicit 'USE WHEN' and 'DO NOT USE FOR' sections covering numerous scenarios, including when to use alternatives like codegen_list_tables, codegen_validate_payload, etc. Also includes preconditions and presentation 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 declare readOnlyHint and idempotentHint, but the description adds value by detailing the CLI command executed, preconditions (restforgejs installed, config file exists), and output format ([+], [-], [~]). 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 well-structured with clear sections and front-loaded purpose. While slightly lengthy, each sentence adds value, including presentation guidance. It could be slightly more concise, but it is well-organized.

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 all necessary aspects: what the tool does, when to use it, preconditions, output format, and presentation guidance. No output schema exists, but the description explains the CLI output adequately. Complete for a complex tool with multiple siblings.

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 description doesn't need to repeat parameter details. However, it adds useful context beyond the schema, such as the default config file name and the behavior when 'table' is omitted. This compensates somewhat, but the schema already covers the basics.

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 function: 'Show the column-level differences between existing payload spec files and the current database schema'. It uses specific verbs and resources, and distinguishes from siblings like codegen_validate_payload and codegen_sync_payload.

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 includes explicit 'USE WHEN' and 'DO NOT USE FOR' sections, listing concrete scenarios (e.g., after drift detection, pre-flight inspection) and providing alternatives for other tasks, such as codegen_validate_payload for quick status and codegen_sync_payload for applying changes.

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 indicate readOnlyHint=false and idempotentHint=false. The description adds behavioral context: it runs a CLI command, writes a payload file, and has preconditions. It also mentions failure behavior. This adds value beyond annotations, but could further detail side effects like overwriting existing files.

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 with clear sections (use when, do not use, preconditions, presentation guidance). Every sentence serves a purpose; no 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?

Given the tool's complexity (3 parameters, no output schema), the description thoroughly covers preconditions, CLI invocation, output file naming, and presentation guidance. It is complete for an agent to use 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%, but the description adds meaning beyond the schema by explaining the cwd precondition, that table is the database table name, and config default. This enhances 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 it generates a payload spec file by introspecting a database table via CLI. It uses specific verbs and resources, and distinguishes from sibling tools like setup_write_env and setup_validate_config.

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 enumerates when to use (e.g., user asks to generate payload, after project config validated) and when not to use (e.g., for credentials or validation), naming alternative tools. This provides comprehensive 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 indicate readOnlyHint and idempotentHint. The description adds that the tool runs `npx restforge-cli dashboard:catalog`, is single source of truth, and includes presentation guidance. No contradictions with annotations. The description enriches transparency with runtime context.

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

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

The description is well-organized into clear sections (USE WHEN, DO NOT USE FOR, PRESENTATION GUIDANCE) and front-loaded with the core purpose. However, it is somewhat verbose, especially the presentation guidelines, which could be trimmed. Still earns its place given 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 complexity of the dashboard catalog and no output schema, the description thoroughly explains what the tool returns, when to use it, prerequisites, and even presentation guidance for the AI. No gaps remain for an agent to understand the tool's role.

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 input schema has 100% description coverage for the single `cwd` parameter. The description does not add significant extra semantics beyond implying the tool runs in that directory. 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 clearly states the tool retrieves the authoritative JSON catalog of dashboard payload spec, listing specific aspects like payload shape, widget structure, params contract, scalar collapse rules, naming conventions, URL pattern, file reference, and placeholder conventions. It also distinguishes itself from sibling tools in the DO NOT USE FOR section.

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 provides an explicit USE WHEN section listing concrete user intents and a DO NOT USE FOR section that names sibling tools and explains when to use them instead. This gives the agent clear guidance on tool selection.

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?

ReadOnlyHint and idempotentHint annotations already indicate safety; description adds that it runs a CLI command, requires restforgejs >= 2.4.0, and is sourced from restforge-cli. No contradictions. Provides context about presentation guidance for the AI, enhancing transparency.

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 with clear sections (USE WHEN, DO NOT USE, etc.) and front-loaded purpose. However, it is relatively long and includes presentation guidance that may not be essential for tool selection, slightly reducing conciseness.

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

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

Despite no output schema, the description fully explains the tool's output (JSON catalog with specific content), prerequisites (package version), execution (runs CLI), and AI presentation hints. For a read-only catalog tool with one parameter, the context is comprehensive.

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% for the single parameter 'cwd', which has a clear description. The description mentions the parameter implicitly ('in the given cwd') but does not add significant new meaning beyond 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 clearly states it retrieves an authoritative JSON catalog of field validation spec, listing specific contents (data types, constraints, etc.). It distinguishes from siblings by naming alternatives like codegen_validate_payload, setup_validate_config, etc., both in USE WHEN and DO NOT USE sections.

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?

Extensive USE WHEN section with concrete scenarios (e.g., user asking about valid constraints, before generating payload) and language-specific example (Indonesian). DO NOT USE lists specific sibling tools and contexts (e.g., validating payload files, generating SQL DDL). This provides explicit guidance for when to use this tool vs 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 and idempotentHint. The description adds context: it runs 'npx restforge-cli query-declarative:catalog' in the given cwd, and the catalog is sourced from restforge-cli to stay in sync. Also includes presentation guidance on language matching and not mentioning internal tool names.

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 somewhat long but well-structured with clear sections (USE WHEN, DO NOT USE FOR, PRESENTATION GUIDANCE). Every sentence serves a purpose, though a few lines could be considered verbose. Overall, it is appropriately detailed for a complex tool.

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 what the catalog contains, when to use, when not to use, and includes presentation guidance. With only one parameter and no output schema, the description provides sufficient context for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100% with a clear description for the only parameter cwd. The description does not add significant meaning beyond the schema—it merely implies the cwd is used to run a command, which is already clear from the schema's description.

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 retrieves an authoritative JSON catalog of query declarative spec, listing specific contents. It distinguishes itself from siblings like codegen_get_field_validation_catalog by noting it's a catalog-style tool with different scope.

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

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

Explicitly provides USE WHEN and DO NOT USE FOR sections, listing numerous specific scenarios and naming alternative tools (e.g., codegen_validate_payload, codegen_generate_payload) for cases where this tool should not be used.

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 and idempotent. Description adds valuable context: live introspection, CLI invocation, preconditions, and presentation guidance. No contradiction.

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?

Well-structured with clear sections, front-loaded summary. However, it is somewhat verbose; could be trimmed without losing clarity.

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?

Covers all aspects: purpose, usage, parameters, preconditions, output format, and presentation guidance. Extremely thorough given no output schema and simple annotations.

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

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

Schema coverage is 100%, but description adds extra context: default config, dialect-aware schema filtering, includeSystem default false, and preconditions. Goes beyond 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?

Clearly states it lists tables and views in the database. Distinguishes itself from siblings like codegen_describe_table by explicitly specifying that it returns only table names and types, not details.

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?

Provides extensive 'USE WHEN' and 'DO NOT USE FOR' sections, detailing exact contexts and alternatives for each sibling. E.g., when to use codegen_describe_table instead.

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

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

The description discloses that sync overwrites files, archives, and restores on failure. Annotations correctly indicate readOnlyHint=false. No contradictions. Additional context about archive cleanup and CLI output is provided.

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 with clear sections, but is somewhat lengthy. Every sentence is justified given the tool's complexity. Front-loaded with core purpose.

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 no output schema, the description covers preconditions, failure handling, and output format comprehensively. It also includes presentation guidance for appropriate agent response.

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?

Input schema has 100% coverage, so baseline is 3. The description adds meaning by explaining defaults (config, output) and behavior when table is omitted, as well as preconditions.

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 applies schema drift to payload files and archives previous versions. It distinguishes from siblings by listing when to use and when not to use, with specific verb+resource scope.

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

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

The description provides explicit USE WHEN and DO NOT USE FOR sections, including specific user utterances and alternative tools. It also advises ordering relative to codegen_diff_payload.

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?

Description discloses read-only, idempotent nature, no file writes, no database access, no registry updates. It adds context beyond annotations (readOnlyHint, idempotentHint) by detailing validation rules, CLI wrapping, and safety for proactive use. 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 lengthy but well-structured with clear sections (purpose, use when, do not use, preconditions, presentation). It front-loads the core purpose. While concise could be improved, it earns its length given 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?

Covers validation scope, use cases, exclusions, preconditions, and presentation guidance. Lacks explicit output format, but states it 'reports whether the payload structure is valid'. Given no output schema, this is acceptable.

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 baseline is 3. Description adds context for some parameters (e.g., 'database' not used in validate-only, 'skipSqlValidation' default behavior, 'name' dash- prefix CLI requirement). This adds meaningful value beyond 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 explicitly states it 'Validate the structural correctness of a dashboard payload spec WITHOUT generating any file', providing a specific verb and resource. It clearly distinguishes from siblings like 'codegen_validate_payload' (which skips dashboards) and 'codegen_create_dashboard' (which generates).

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?

Extensive 'USE WHEN' and 'DO NOT USE FOR' sections explicitly list scenarios and alternatives, such as using 'codegen_validate_payload' for CRUD or 'codegen_create_dashboard' for generation. It also mentions workflow positioning (pre-flight before generation).

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?

Description adds preconditions (restforgejs installed, config file), explains the CLI runs without modifying files, and reports per-file status. Consistent with annotations readOnlyHint and idempotentHint.

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?

Well-structured with sections, front-loaded summary, and no redundant sentences. Slightly long but all content is valuable for agent understanding.

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 covers purpose, usage guidelines, preconditions, presentation guidance, and how it relates to siblings. Annotations provide safety profile. Completes all required context.

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?

Input schema has 100% coverage with descriptions. The description reinforces default values (config, output) and explains behavior when table is omitted, adding meaningful context beyond 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 clearly states the tool validates that payload spec files are in sync with the database schema, using a specific CLI command. It distinguishes from siblings by explicitly listing what it does not cover.

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?

Includes 'USE WHEN' and 'DO NOT USE FOR' sections with concrete examples and alternative tool names, providing clear decision 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 (readOnlyHint, idempotentHint) are supplemented by detailed behavioral info: tool runs EXPLAIN without executing rows, rejects non-SELECT statements, is idempotent and read-only, and describes error handling and preconditions. 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?

Well-structured with clear sections (USE WHEN, DO NOT USE, Preconditions, PRESENTATION GUIDANCE) and front-loaded core purpose. Each part is necessary given the tool's complexity, no wasted sentences.

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

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

No output schema, but description compensates by explaining return behavior (pass/fail, error categories), preconditions (restforgejs version, config file), and presentation guidance. Covers all necessary aspects 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?

Input schema has 100% description coverage; the description re-explains each parameter with additional context (e.g., SQL must be SELECT or WITH, config can auto-fallback to config/ subfolder). Adds value by reinforcing constraints beyond 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 clearly states the tool validates a SELECT (or WITH/CTE) SQL statement against the live database, checking syntax, column references, function existence, type compatibility, and JOIN resolution. It distinguishes from siblings like codegen_validate_payload by specifying SQL validation vs payload validation.

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 'USE WHEN' and 'DO NOT USE FOR' sections list specific use cases and exclusions, including alternative tools for JSON shape, table listing, and other tasks. Cross-references sibling tools (codegen_list_tables, codegen_describe_table) provide clear when-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 declare readOnlyHint and idempotentHint; the description adds that the tool runs in-process, does not touch filesystem/network/RESTForge, and outputs 'pong' with timestamp and version. This context goes beyond the structured 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?

Well-structured with clear sections (USE WHEN, DO NOT USE, presentation guidelines). Front-loaded with purpose. Slightly verbose with presentation guidance, but each section serves a purpose.

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 simplicity (1 optional param, no output schema), the description covers all necessary aspects: purpose, usage scenarios, behavioral constraints, and output format. No gaps.

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

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

The single optional 'message' parameter has 100% schema description coverage ('Optional message to echo back'). The description only mentions it in output context, adding marginal value beyond 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 explicitly states it is a 'smoke test tool to verify the MCP server is up and responsive.' It clearly distinguishes itself from RESTForge operations, making the purpose 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?

Includes a 'USE WHEN' section listing specific scenarios and a 'DO NOT USE FOR' section with explicit alternative tools like 'setup_validate_config' and 'setup_read_env', providing clear guidance on when to invoke this 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?

Annotations already indicate readOnlyHint and idempotentHint; the description adds behavioral details like read-only, no creation/overwrite, and fixed file names per os+mode, but doesn't cover return format.

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?

Well-structured with clear sections and bullet points, each sentence adds value; no unnecessary verbiage despite moderate length.

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

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

No output schema and description doesn't explain what the tool returns (e.g., list of files or boolean), which is a gap for a simple check tool. Otherwise complete for usage context.

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?

Input schema covers 100% of parameter descriptions, so baseline is 3. The description adds file name details but doesn't enhance parameter understanding beyond 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 clearly states the tool checks existence of launcher files produced by runtime_generate_launcher, uses specific verbs, and distinguishes from sibling tools like runtime_generate_launcher and runtime_check_status.

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 USE WHEN and DO NOT USE FOR sections provide clear context and alternatives, such as using runtime_generate_launcher for generation and generic Read tools for reading content.

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 declare readOnlyHint=true, and the description adds rich behavioral details: detection order (PID file, port probe, PM2, HTTP probe), the fact that current launchers don't write PID file, that a port in use doesn't guarantee it's the server, and caveats about host address. 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 well-structured with clear sections (e.g., USE WHEN, DO NOT USE FOR, Detection modes, Note on host-mode detection) and bullet points. It is slightly verbose but every sentence adds value. Front-loads the main purpose effectively.

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 complexity (7 parameters, multiple detection modes, HTTP probe, no output schema), the description is thorough. It covers preconditions, detection flow, presentation guidance, and caveats (e.g., stale PID file, interface mismatch). No output schema, but the description sufficiently explains return states (running, dead_pid, etc.).

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 baseline is 3. The description adds significant meaning beyond the schema: explains detection modes, when each parameter is required (e.g., 'port' for port detection and health_path, 'project' for pm2 mode), and provides context like 'host_address' default and interaction with health_path.

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 'Check whether the RESTForge Server is currently running' (specific verb+resource). It lists detection modes and preconditions, and distinguishes from sibling tools like runtime_generate_launcher and runtime_validate_preflight by explicitly stating what the tool is not for.

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 includes a 'USE WHEN' section with explicit scenarios (e.g., user asks 'is the server running?'), and a 'DO NOT USE FOR' section listing alternatives (e.g., use 'runtime_generate_launcher' for generating launchers). This provides clear guidance on when to use this tool versus 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?

Adds significant context beyond annotations: scanning behavior, presentation guidance, precondition handling, and filename usage. Annotations already indicate read-only/idempotent.

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?

Well-structured with clear sections (USE WHEN, etc.), but slightly verbose. Every sentence adds value.

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

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

No output schema, but description explains return value (list of filenames) and how to use it. Preconditions and edge cases addressed.

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 covers cwd with 100% description. Description reinforces the precondition that config/ must exist relative to cwd, adding value.

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 detects RESTForge config files by scanning the config/ folder for .env files. It differentiates from siblings via explicit DO NOT USE examples.

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?

Provides explicit USE WHEN conditions (e.g., user asks for available configs, before generating launcher) and DO NOT USE scenarios with alternative tool names.

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 adds behavioral context beyond the annotations: it explains that detection scans JS files, mentions preconditions (folder existence), and details presentation rules (language matching, auto-proceed vs. ask user). Since annotations already declare readOnly and idempotent, the description effectively supplements them without contradiction.

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 with headers and bullet points, making it easy to scan. While it is longer than minimal, each section (USE WHEN, DO NOT USE FOR, Preconditions, PRESENTATION GUIDANCE) earns its place by adding essential guidance. Could be slightly tightened but remains effective.

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 provides complete context for a simple detection tool: it explains the detection logic, preconditions, usage boundaries, and presentation rules. No output schema is needed because the output is implicitly a list of project names. The description fully equips an AI agent to select and invoke 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 baseline is 3. The description adds value by explaining that 'cwd' must contain 'src/modules/' and that the folder's existence is a precondition. This provides meaningful context beyond the schema's basic parameter description.

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 specific verb ('Detect') and resource ('RESTForge project names by scanning the conventional 'src/modules/' folder'). It distinguishes itself from sibling tools like 'runtime_detect_config' by focusing on project names from module files.

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 includes explicit 'USE WHEN' and 'DO NOT USE FOR' sections that list specific user queries and contexts. It names alternative tools for different tasks (e.g., 'runtime_detect_config' for config files), providing clear guidance on when to choose this tool over 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 declare destructiveHint=true and readOnlyHint=false; the description adds details on file generation, modes, and the intentional design choice (AI session termination). No contradictions, and it enriches understanding beyond 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 comprehensive yet well-organized with sections (purpose, file details, use cases, preconditions, presentation guidance). Every sentence adds value, and the most critical info (it generates, doesn't run) 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?

Given the tool's complexity (10 parameters, no output schema), the description covers all aspects: purpose, exact file outputs, usage contexts, parameter constraints, and post-generation instructions. It leaves no 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 coverage is 100%, but the description significantly adds meaning: explains os/mode file naming, mutual exclusivity of cluster/workers, and watch disallowed with pm2. This goes well beyond the schema's basic 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 explicitly states 'Generate a launcher script for the RESTForge Server' and clarifies that it does not run the server, distinguishing it from sibling tools like runtime_check_status. This provides a specific verb and resource.

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 provides clear when-to-use conditions (user asks to run the server) and when-not-to-use (actual server start/stop, modifying DB schema). It also lists preconditions and alternatives, making it easy for agents to decide.

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 and idempotentHint=false. The description reinforces this by stating preflight failure is informational and not a blocker, and explains the best-effort nature of the port check. No contradictions are present.

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 with clear sections (USE WHEN, DO NOT USE FOR, Preconditions, PRESENTATION GUIDANCE). It is front-loaded with the purpose and every sentence adds value without 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?

Although no output schema exists, the description provides presentation guidance and notes the informational nature of failures. However, it lacks explicit details on the return format (e.g., structured object vs. text). This minor gap prevents a perfect score.

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 baseline is 3. The description adds context for the 'port' parameter ('tries to bind locally to detect if the port is free'), which is beyond the schema's description. For 'cwd' and 'config', the description aligns with the schema but does not add significant new meaning.

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 explicitly states the tool runs a runtime preflight check before generating a launcher, detailing the components inspected (license, database, redis/kafka, PID file, port). This clearly distinguishes from sibling tools like 'setup_validate_config' and 'runtime_generate_launcher'.

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 includes dedicated 'USE WHEN' and 'DO NOT USE FOR' sections that specify conditions (e.g., before invoking 'runtime_generate_launcher', after config changes) and explicitly name alternative tools (e.g., 'setup_validate_config', 'setup_read_env'). This provides excellent guidance for tool selection.

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 provide readOnlyHint=false and idempotentHint=false. The description adds implementation detail (fs.mkdir with recursive: true), output format (absolute path), and collision handling behavior (force flag frames as choice/question).

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?

Well-structured with sections and bullet points, but somewhat lengthy. Each section earns its place: purpose, usage, internals, output, presentation. Front-loaded with main action.

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

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

Despite no output schema, output is clearly described (absolute path) with usage guidance for subsequent tools. Presentation guidance adds completeness for agent interaction. Adequately covers all necessary context.

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 parameter descriptions. The description reinforces defaults (folderName) and clarifies force behavior beyond schema, adding moderate value.

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 begins with a clear, specific verb+resource: 'Create a new folder to serve as the root of a RESTForge project.' It lists contents and explicitly distinguishes from siblings via 'DO NOT USE FOR' referencing other 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?

Includes a 'USE WHEN' section with concrete user phrases and a 'DO NOT USE FOR' section naming alternative tools. Also states natural next step, making usage context 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?

Annotations already indicate read-only and idempotent. The description adds operational details (command execution, version requirement) and data freshness (single source of truth). No contradictions.

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?

Well-structured with clear sections, but the presentation guidance adds length. Could be slightly more concise, but overall effective.

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 simplicity (one param, no output schema), the description covers purpose, usage, prerequisites, and even response formatting. Fully complete for the context.

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 a description for the cwd parameter. The description does not add new meaning beyond the schema, so 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 clearly states it fetches the JSON schema of config parameters, with a specific verb and resource. It distinguishes from sibling tools like setup_read_env and setup_write_env.

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 USE WHEN and DO NOT USE FOR sections list scenarios and alternatives, providing clear guidance for when to use this tool versus others.

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 set readOnlyHint=true and idempotentHint=true. The description adds context: 'Runs npx restforge-cli config:template', 'READ-ONLY and safe to call repeatedly', 'No file is written', and a version requirement. 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?

Well-structured with clear sections (USE WHEN, DO NOT USE FOR). Front-loaded with core purpose. Presentation guidance is extra but relevant. Could be slightly more concise by merging some points, but overall efficient.

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 one parameter and no output schema, the description fully explains what the tool does, when to use it, its safety profile, and internal command. Includes version prerequisite. No gaps.

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

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

Only one parameter (cwd) with high schema description coverage (100%). The schema already explains 'Absolute path of the project folder (must have restforgejs installed)'. Description doesn't add significant new parameter info beyond restating the requirement.

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 'Get raw template content of db-connection.env without writing any file.' It clearly identifies the resource (template content), action (get), and key behavior (no file writing). It distinguishes from siblings like setup_init_config and setup_read_env.

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?

Provides explicit use cases (drift detection, comparing config after modification) and a 'DO NOT USE FOR' section listing three sibling tools with their purposes. Includes example user queries in multiple languages.

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?

Describes generated files and mentions 'reset them to the default template' implying destructive behavior, consistent with readOnlyHint=false. Annotations already cover non-idempotent nature.

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?

Well-structured with sections, but includes presentation guidance that adds length. Still clear and readable.

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?

Covers purpose, usage, preconditions, and output files. Complete for a simple tool with one parameter and no output schema.

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

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

Single parameter cwd has full schema coverage (100%), and description adds context by stating the tool runs in the given cwd and generates files there.

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 starts with a clear verb 'Generate' and specific resource 'skeleton config and sample payloads', and distinguishes from siblings like setup_install_package and setup_write_env.

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?

Provides explicit 'USE WHEN' and 'DO NOT USE FOR' sections with conditions and alternatives, e.g., 'DO NOT USE FOR: Installing restforgejs -> use setup_install_package'.

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 that the tool runs 'npm install restforgejs@<version>' in cwd (local install), defaults to 'beta' version, and notes that setup_init_config will return a precondition message if not run first. Annotations already indicate idempotentHint=true and readOnlyHint=false, so the description adds behavioral context beyond 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 relatively long but well-structured with sections (USE WHEN, DO NOT USE, positioning note, presentation guidance). Every section adds value. Could be slightly more concise, but the structure aids clarity.

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

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

Given the tool has 2 params, no output schema, and annotations present, the description covers prerequisites (folder exists), exact command, version semantics, and even agent presentation behavior. It thoroughly addresses what the agent needs to know to invoke 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 has 2 parameters with 100% description coverage. Description adds extra context: cwd must exist before running, and explains why default version is 'beta' (RESTForge is a public pre-release). This adds meaning beyond the schema alone.

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 title 'Install restforgejs Package' and description clearly state the tool installs the restforgejs package via npm. The description uses specific verb 'install' and resource 'restforgejs package', and distinguishes from sibling tools by listing what the tool is NOT for (e.g., creating folder, generating config).

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?

Provides explicit 'USE WHEN' scenarios (e.g., user wants to install RESTForge, setup before configuration, update to specific version) and 'DO NOT USE FOR' list that references sibling tools (setup_create_folder, setup_init_config, etc.). Also positions the tool in the setup chain, giving clear context for when to invoke it.

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 mark readOnlyHint and idempotentHint; description adds that the tool is read-only, safe to repeat, masks sensitive fields by default, and the unmask parameter behavior. No contradiction.

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?

Well-organized with clear sections but slightly long; some redundancy (e.g., 'READ-ONLY' repeated). Still effective and 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?

Perfectly complete: covers purpose, usage, parameters, behavior, presentation, and error conditions. No gaps considering the tool's role and lack of output schema.

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

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

Schema covers all 3 parameters with descriptions. Description adds guidance on unmask usage and default masking, enhancing understanding beyond 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?

Title and description clearly specify the action (read and parse) and resource (config/db-connection.env). Distinguishes from siblings like setup_write_env, setup_update_env, and setup_validate_config by name and scope.

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

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

Explicit 'USE WHEN' list covering multiple scenarios and 'DO NOT USE FOR' with alternative tools. Also includes presentation guidance for safe interaction.

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 detailed behavior: reading existing file, replacing matching keys while preserving inline comments, appending new keys, auto-quoting values with special characters, and handling types. 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?

Well-structured with clear sections but includes a 'PRESENTATION GUIDANCE' section that, while useful, adds length. Not overly verbose.

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?

Comprehensive for a tool with 3 parameters and no output schema; covers behavior, usage alternatives, and presentation guidelines. An agent can use it correctly without additional context.

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 baseline is 3. Description adds value with an example for 'fields' and clarifies type handling, but doesn't add much for 'cwd' or 'configFile'.

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 it applies a partial update to config/db-connection.env by merging key/value pairs, preserving comments and untouched parameters. It distinguishes from siblings by listing what not to use it for.

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 USE WHEN and DO NOT USE FOR sections with specific scenarios and direct references to sibling tools (setup_init_config, setup_write_env, setup_validate_config).

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 and idempotentHint. The description adds that it runs 'npx restforge validate' and explicitly states 'read-only and safe to call repeatedly', reinforcing safety but adding moderate value beyond 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 main purpose and well-organized into USE WHEN, DO NOT USE, presentation guidance. While somewhat long, each section contributes essential guidance; minor redundancy could be trimmed.

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 two parameters and no output schema, the description covers validation scope, preconditions, and presentation guidance. It lacks explicit output format but addresses handling of results (e.g., summarizing, no raw output). Relatively complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'cwd' and 'configFile' with the default value, consistent with schema but not adding significant new meaning. Adequate given high coverage.

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 verb 'validate' and resource 'RESTForge config' (license, database, redis, kafka). It distinguishes from sibling tools like codegen_* and setup_write_env via explicit DO NOT USE conditions, making the purpose 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?

Provides comprehensive USE WHEN conditions (e.g., after filling credentials, before runtime) and DO NOT USE list referencing specific alternatives. Includes multi-language examples and a suggestion to call setup_read_env first, covering when to use and when not to.

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 indicate it is a write operation (readOnlyHint=false) and idempotent (idempotentHint=true). The description adds that it reads the existing file, updates specific fields in place, appends missing keys, and preserves comments/blank lines. This reveals behavior beyond annotations, though it could explicitly mention that it overwrites existing values for the updated 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 comprehensive and well-structured with sections (USE WHEN, DO NOT USE, Behavior, PRESENTATION GUIDANCE) but is somewhat lengthy. The front-loading is effective, but the presentation guidance section is verbose and somewhat tangential to the tool's core behavior.

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

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

Given the tool has 10 parameters and no output schema, the description covers most essential aspects: purpose, when to use, behavioral details, and output file location. It mentions handling of missing keys but omits details about error handling or file non-existence (though implied in presentation guidance). Overall, it is relatively complete.

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 only 10%, but the description groups parameters into 'license, server settings, and database credentials', which adds context. However, it does not explain each parameter's meaning, format (e.g., pattern for license), or default values, leaving room for ambiguity.

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: 'Write license, server settings, and database credentials into config/db-connection.env using a partial-merge strategy'. It explicitly differentiates from siblings by naming alternative tools for different tasks (e.g., setup_init_config, setup_update_env).

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 includes dedicated 'USE WHEN' and 'DO NOT USE FOR' sections that explicitly specify when to use this tool vs. alternatives, providing concrete conditions and naming sibling tools for clarity.

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