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

With no annotations provided, the description carries the full burden of behavioral disclosure. It notes that the project must be 'running', which is a useful prerequisite, and lists what information is included. It does not explicitly state whether the command is read-only or what happens if the project is not running, but the 'Get a detailed description' wording implies a non-destructive inspection.

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 short and front-loaded, immediately stating the tool's purpose and scope. It includes aliases and a usage line without unnecessary verbosity. Every sentence provides useful information, and the pointer to 'ddev help describe' is a concise way to handle further details.

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

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

Given that there is no output schema, the description does a good job of summarizing what will be returned (name, location, URL, status, MySQL connection details, Mailpit, etc.) and notes the 'running' prerequisite. It does not describe error cases or explicitly state that it is read-only, but for a simple describe tool with one optional parameter, it is nearly 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?

The input schema already fully describes the single parameter with 100% coverage: 'Path to the DDEV project directory'. The description's usage line uses 'projectname' rather than 'projectPath', which could introduce slight ambiguity but does not add meaningful semantic detail beyond the schema. The baseline of 3 is appropriate for high schema 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 starts with a specific verb 'Get' and clearly identifies the resource as 'a detailed description of a running DDEV project', listing example contents like name, location, URL, status, MySQL connection details, and Mailpit. This distinguishes it from sibling tools like ddev_export_db, ddev_logs, or ddev_snapshot, which perform different operations.

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 usage syntax ('Usage: ddev describe [projectname] [flags]') and points to 'ddev help describe' for full options, giving some practical guidance. However, it does not explicitly state when to use this tool over alternatives, such as ddev_list or ddev_logs, or mention conditions or exclusions. The usage context is implied rather than clearly articulated.

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 burden. It discloses a key safety behavior: 'Dangerous commands blocked unless ALLOW_DANGEROUS_COMMANDS=true.' It also mentions default service and workdir mapping. However, it does not describe output format, exit code handling, or whether commands are executed via a shell, leaving notable behavioral gaps for an execution 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 front-loaded with a clear purpose statement, but the extensive list of common use cases across many frameworks makes it long. While well-organized with headers and bullets, it could be more concise; many examples are redundant for an AI agent that can infer typical commands.

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 absence of output schema and annotations, the description compensates with comprehensive examples, service routing details, and safety disclaimers. It covers all necessary aspects for correct invocation, but lacks information about return values, timeouts, or prerequisites (e.g., project must be running), leaving minor completeness 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?

Schema description coverage is 100%, setting a baseline of 3. The description adds value beyond the schema by providing a detailed 'Common Use Cases' section with concrete command examples and by explaining that 'workdir maps to ddev --dir' and the default service, enriching 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 opens with 'Execute a shell command in the container for a DDEV service,' clearly stating the verb (execute), resource (shell command in DDEV container), and scope. It distinguishes itself from sibling tools like ddev_logs and ddev_export_db by emphasizing generic command execution and service selection.

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 schema's command description explicitly says 'For Drush commands, use ddev_drush. For Composer commands, use ddev_composer,' providing clear alternatives. The service description also explains auto-routing (e.g., npm/php commands → web, mysql → db), giving concrete when-to-use guidance. The main description adds default service and workdir mapping.

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 burden. It discloses key behaviors: output to file or stdout, supported compression types, and the default target database. It also shows how MCP arguments translate to CLI flags. However, it does not mention side effects, permission needs, or error conditions, leaving some behavioral ambiguity.

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 compact and well-structured. It leads with the core purpose, then provides usage, flag mapping, and a pointer to full help. Every sentence is informative with minimal 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 moderate-complexity tool with 4 parameters and no output schema, the description covers the essential usage context: command syntax, defaults, and where to find more details. It lacks examples, but the pointer to 'ddev help export-db' mitigates this. Overall, it is sufficiently complete for an agent to 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 the baseline is 3. The description adds value by explaining the mapping between MCP args and CLI flags (e.g., file → -f/--file, targetDb → -d/--database, compressionType → --gzip|--bzip2|--xz) and by stating defaults (targetDb default 'db', compression default gzip), which go beyond the schema descriptions.

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

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

The description clearly states the tool's function: "Dump a database to a file or stdout." It specifies the resource (database), the action (dump/export), and output options (file or stdout), distinguishing it from sibling tools like ddev_import_db and ddev_snapshot.

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 concrete usage guidance including the command syntax, MCP-to-CLI flag mappings, and default values (targetDb default "db", compression default gzip). It does not explicitly exclude alternatives or state when not to use, but the context is clear enough for an agent to select this tool for exporting databases.

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 full burden of explaining behavior. It discloses that the tool returns the same output as shell help commands and clarifies the format for different argument combinations. It also states that projectPath is not required for help, which is useful behavioral context. It does not explicitly mention side effects, but for a help tool this is sufficient.

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 organized into a clear introduction, usage syntax, and examples. While longer than two sentences, every part contributes useful information: the purpose, when to use, exact syntax, and examples. It is front-loaded with the core purpose and then provides supporting details without excessive verbosity.

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 and the absence of an output schema, the description provides sufficient context: what it does, how to use it, and what output to expect (same as shell help). It covers all parameter combinations and examples. It does not over-explain return values, which is appropriate since the output is standard help 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 input schema already describes all three parameters with 100% coverage. The description adds value by providing concrete examples (e.g., command="import-db" → ddev help import-db; command="snapshot", subcommand="restore" → ddev snapshot restore --help) and clarifying that projectPath is optional and not needed for help. This goes 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 clearly states the tool's purpose: "Get help for any DDEV command." It uses a specific verb (get help) and resource (DDEV command), and distinguishes it from sibling tools that perform actual DDEV operations like start, stop, or snapshot. The inclusion of shell-equivalent examples reinforces the purpose.

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 says "Use when you need exact flags, examples, or usage for a ddev command," providing clear context for when to invoke this tool. It also gives usage patterns and examples for combining command and subcommand. However, it does not explicitly mention when not to use it, though no alternative help tool exists among the 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?

With no annotations, the description carries the burden of disclosing behavior. It reveals supported formats, archive extraction behavior, and the default targetDb. However, it omits critical behavioral aspects such as whether an existing database is overwritten, permissions needed, or what the command outputs on success/failure.

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 compact and front-loaded: the main action is stated first, followed by a concise list of supported formats and usage details. Every sentence contributes useful information, though the usage line is a bit terse and tucks projectPath away.

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 does not explain the return value or success/failure behavior, which is a gap for an import operation. It also does not describe the projectPath parameter in the text, though it appears in the schema. The tool is relatively simple, but lacks coverage of side effects and output.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches this by mapping each MCP arg to the corresponding ddev flag (src → --file, targetDb → --database, extractPath → --extract-path), and clarifies the default for targetDb ('default "db"') and the purpose of extractPath. This adds practical 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 uses a specific verb and resource: 'Import a SQL dump file into the project.' It clearly distinguishes from sibling ddev_export_db by the action (import vs export) and lists supported file formats, leaving no ambiguity about the tool's purpose.

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 usage syntax ('Usage: ddev import-db [project] [flags]') and an MCP arg-to-flag mapping. Gives conditional guidance for archives ('For archives, use extractPath'). Does not explicitly state when not to use this tool versus alternatives, but the context is clear and actionable.

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 discloses default behavior (shows all) and the effect of activeOnly, but does not explicitly mention side effects, permissions, or return format. As a listing tool, it is likely read-only, but this is not stated.

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 concise and front-loaded with a clear purpose statement. It includes usage and flag information in a compact format. Every line serves a purpose, though the flag line introduces a schema mismatch, but that is a content issue, not a conciseness issue.

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 list tool with no output schema and no annotations, the description is fairly complete. It explains default behavior, the parameter's effect, and usage. It lacks explicit guidance on when to use alternatives and does not describe output structure, but these are minor for such a straightforward tool. The unsupported flag mention is a notable gap.

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

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

The schema already documents activeOnly with 'Show only running projects' (100% coverage). The description adds default behavior but also mentions flags '-t/--type' which are not present in the input schema. This is misleading and could lead the agent to attempt passing a 'type' parameter that the tool definition does not accept.

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: 'List DDEV projects and their status.' The verb 'list' and resource 'DDEV projects' are specific, and the mention of showing all by default or active only distinguishes it from sibling tools like ddev_start, ddev_stop, and ddev_describe.

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 usage context for the activeOnly parameter ('use activeOnly for running only') but does not explicitly state when to choose this tool over alternatives like ddev_describe or ddev_logs. There are no exclusions or alternative recommendations, so usage 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?

With no annotations, the description carries the full burden. It discloses that the tool displays stdout logs via docker logs and implies streaming behavior through the --follow flag. However, it doesn't mention potential long-running behavior with -f or any prerequisites like a running project, leaving some behavioral gaps.

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 concise and well-structured: a clear purpose first, followed by usage and flags, all in three short sentences. Every line adds value, and the pointer to 'ddev help logs' avoids unnecessary detail.

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 logs tool with all optional parameters and no output schema, the description covers the essential behavior, defaults, and flags. It doesn't describe return values, but that's expected for logs. The only minor omission is explicit explanation of the projectPath parameter, though it's implied in the usage line.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by explaining the default service and giving a concrete example for the service parameter, plus mapping CLI flags to parameters. It also hints at projectPath through the '[projectname]' positional argument.

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: 'Display stdout logs from DDEV services (docker logs).' It uses a specific verb and resource, and the focus on logs distinguishes it from sibling commands like ddev_export_db or ddev_exec.

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 concrete usage context, including the default service ('Default: web service') and an example for selecting a different service ('use service for e.g. db'). It also lists common flags, making it easy to understand when to use this tool, though it doesn't explicitly exclude 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?

With no annotations, the description carries full burden. It discloses that all projects and containers are stopped, the Mutagen daemon is stopped if running, and it is equivalent to a command that also stops the SSH agent. This is thorough for a simple stop/poweroff operation.

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 compact: three sentences that front-load the core function, then add the Mutagen daemon behavior and usage/help pointers. Every sentence adds value with 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?

For a zero-parameter tool with no output schema, the description fully addresses what it does, the affected scope, and the extra daemon behavior. It is complete for the tool's simplicity.

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 tool has zero parameters, so the baseline is 4. The description mentions flags generically but does not add any parameter-specific meaning, and the schema already covers everything (empty properties). This is acceptable for a no-parameter tool.

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 'Stop all DDEV projects and containers' with a specific verb and scope. This differentiates it from sibling ddev_stop, which likely targets individual projects, and also mentions the Mutagen daemon side effect.

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 clear context that this is for stopping all projects rather than a single one, and cites the equivalent ddev command. However, it does not explicitly name alternatives like ddev_stop or state when not to use 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?

With no annotations, the description must disclose all behavioral traits. It does state 'stops then starts', but it introduces conflicting invocation details: the schema expects a single 'projectPath', while the description mentions multiple 'projectname' arguments and CLI flags not present in the schema. It also fails to mention confirmation behavior, side effects on running processes, or error handling, leaving significant ambiguity.

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 relatively short, with a clear first sentence followed by usage and flags. It earns its place by giving actionable CLI context, though the 'Usage' line is somewhat redundant with the first sentence and the schema. Overall, it is concise and well-structured, but not maximally 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?

The tool is simple, but the description lacks essential context: no return value description, no mention of what happens if the project is not running, and no clarification on how the schema's projectPath relates to the projectname syntax. The parameter mismatch severely undermines the completeness for an agent trying to 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?

The schema already describes projectPath clearly, so the baseline is 3. However, the description adds 'projectname ...' and flags like -a/--all and -y/--skip-confirmation, which are not reflected in the schema. This creates confusion rather than enriching the meaning of the actual parameter, potentially misleading an agent about what input is expected.

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 'Restart a DDEV project: stops then starts named project(s)', which uses a specific verb and resource. It also distinguishes itself from sibling tools like ddev_start and ddev_stop by explicitly defining the restart operation as the combination of stop and start.

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 usage syntax and flags, implying when to use it (for restarting projects), but it does not explicitly compare to alternatives like ddev_start, ddev_stop, or ddev_poweroff. There is no 'use this instead of X when...' guidance, so the usage context is only partially clear.

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

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

With no annotations, the description must carry the full burden of behavioral disclosure. It mentions the storage location (.ddev/db_snapshots) and the -y flag to skip confirmation, which provides some safety context. However, it does not disclose that 'cleanup' is destructive (deleting snapshots) or that 'restore' overwrites the current database, which are significant behavioral traits for an agent to know.

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 densely packed but well-organized, front-loading the core purpose and then listing actions and flags. It includes a usage line and pointers to help commands, with no redundant or filler 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?

Given the tool's complexity (six parameters, four actions, no output schema), the description covers all actions and key flags, and references 'ddev help snapshot' for full options. It does not describe output format or fully clarify projectPath usage, but it is otherwise adequate for an agent to execute the main workflows.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by clarifying that 'name' is for create, 'snapshotName' is for restore, and that '--latest' can substitute for a snapshot name. This goes beyond the schema's generic descriptions and guides correct parameter usage.

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

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

The description opens with 'Create, list, restore, or cleanup database snapshots', clearly specifying the verb and resource. It further distinguishes the tool by noting snapshots are stored in .ddev/db_snapshots, which separates it from sibling database tools like import/export.

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 action-specific instructions, e.g., 'Restore with action=restore and snapshotName; use ddev snapshot restore --latest for latest.' It also lists all actions and flags, giving clear context for each. It does not explicitly exclude any sibling tools, but the multi-action scope makes internal guidance sufficient.

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 full behavioral disclosure. It discloses that the tool initializes and configures containers, and mentions flags like --skip-confirmation and --skip-hooks, but does not state potential side effects, prerequisites (e.g., Docker running), or what happens if the project is already started.

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 compact and front-loaded, with a clear purpose statement, usage line, and relevant flags. It includes a helpful pointer to 'ddev help start' for full options, with no redundant information.

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 start command with three parameters and no output schema, the description covers purpose, usage, and key flags. It could mention prerequisites or idempotency, but overall it is sufficiently complete 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?

Schema description coverage is 100%, so the baseline is 3. The description does list the flags and mentions projectPath implicitly through 'pass project name(s)', but it largely mirrors the schema without adding new semantic details.

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 starts a DDEV project environment and initializes/configures web server and database containers. This distinguishes it from siblings like ddev_stop and ddev_restart by explicitly describing the start action and its 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?

Provides clear context on when to use it ('Start a DDEV project environment') and how to invoke it ('Run from project directory or pass project name(s)'). It lists relevant flags but does not explicitly mention alternatives or when not to use, such as preferring ddev_restart for already-running projects.

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 competently discloses key behaviors: 'Non-destructive: leaves database and code intact' and 'Stop and remove the containers.' It also notes the need to run from a project directory or provide a project name, which is a practical behavioral requirement. The existence of destructive flags is hinted by referencing help output.

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 brief and well-structured: one sentence for the core action and safety, one for usage, and one pointing to help for advanced options. 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?

For a simple stop command with one parameter and no annotations, the description covers all essential aspects: what it does, safety implications, how to invoke it, and where to find more options. It does not describe return values, but that is not expected for this type of command and no output schema is provided.

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 already provides a clear description for the single parameter projectPath. The description adds contextual usage ('Run from project dir or pass project name(s)') and shows the CLI equivalent, but it may create slight ambiguity by implying project names are acceptable while the schema only mentions a path. Since schema coverage is 100%, a baseline of 3 is appropriate.

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

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

The description clearly states the action: 'Stop and remove the containers of a DDEV project.' This gives a specific verb and resource, and it differentiates from sibling tools like ddev_start and ddev_restart. The clarification that it is 'Non-destructive' further defines its 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 clear context: 'Run from project dir or pass project name(s).' It also directs users to 'ddev help stop' for additional flags like --remove-data and --snapshot. However, it does not explicitly mention when to use this tool over alternatives like ddev_poweroff or how it differs from them.

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 transparency burden. It clearly states the command 'Display the version' and shows that flags are supported, indicating a read-only informational operation. It does not discuss output details or potential error states, but for a simple version command this level of clarity is sufficient.

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 minimal and front-loaded with the main purpose, followed by two short, useful usage lines: 'Usage: ddev version [flags]' and 'For full options: ddev help version.' Every sentence earns its place 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?

For a zero-parameter, read-only version command, the description provides the core purpose and usage. It does not describe the exact output format, but the absence of an output schema and the tool's simplicity make this acceptable. Contextual completeness is strong given sibling tools exist for more complex operations.

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 zero parameters, so there are no parameter semantics to clarify. The description adds no unnecessary parameter-related content, and the zero-parameter baseline of 4 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 uses a specific verb 'Display' and clearly identifies the resource: 'the version of the DDEV binary and its components.' This unambiguously distinguishes it from sibling tools like ddev_start or ddev_exec, which have different purposes.

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 direct usage line ('Usage: ddev version [flags]') and points to 'ddev help version' for full options, providing basic invocation guidance. However, it does not explicitly state when to prefer this tool over alternatives or mention context/exclusion 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?

No annotations are provided, so the description carries the burden. It states the action (sending a notification) and implies a non-destructive, simple operation, but does not disclose details like blocking behavior, permissions, or response output. This is acceptable for a simple tool but lacks depth.

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, focused sentence that accurately summarizes the tool without unnecessary detail. Every word earns its place.

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 tool with two well-documented parameters and no output schema, the description is mostly complete. However, it misses the contextual cue from the name ('complete_notification') that this is intended for notifying completion of tasks, which would help an agent know when to invoke it.

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

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

Schema description coverage is 100%, and both parameters (title, message) are self-explanatory. The description adds no additional meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('send') and resource ('OS notification'), clearly distinguishing it from the sibling ddev commands. It is unambiguous and immediately understandable.

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 provided on when to use this tool or how it relates to alternatives. The name implies it is for completion notifications, but the description does not state this context or any exclusions.

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