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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description usefully reinforces that this reads live server state ('actual remote directories'), but adds nothing about return shape, whether hidden files or symlinks appear, or any permission/size limits.

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

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

Two sentences, each earning its place: the first defines the action and scope, the second the workflow trigger. The purpose is front-loaded with zero filler.

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

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

For a read-only, fully-annotated, fully-documented exploration tool this is close to complete; the workflow cue is genuinely helpful. The only notable gap is that with no output schema, the description never states what is returned (a listing? entries with types?), forcing the agent to infer.

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% — path, project and environment are all documented in the schema with defaults. The description adds no extra semantics such as path syntax, relative vs. absolute handling, or what 'environment' means for browsing. Baseline 3 applies.

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

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

States a specific verb pair (Inspect/browse) and resource (remote directories and files on the hosting server), which is more concrete than a bare name restatement. It doesn't explicitly name the sibling it contrasts with (set_remote_path / download_remote_file), but the 'explore before picking a destination' framing makes the distinction inferable.

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

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

'Use this to explore what folders exist on the server before picking a remote deployment destination' gives a clear trigger condition tied to the deployment workflow. No explicit when-not or named alternatives (e.g., vs. set_remote_path) are provided, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=true; the description adds genuinely non-redundant context about how credentials are obtained (Keychain/SecretService/Vault) and that passwords are never exposed. It also partially names destructive consequences ('deleted files', 'failed ... deletes'), but does not warn about server-only file deletion or the confirmation gate, which is the riskiest behavior.

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

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

Three tightly packed sentences: action and scope first, security guarantee second, return payload third. No filler and no repetition of schema 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?

With no output schema, the description usefully enumerates the JSON report fields, and credentials handling is covered. The main missing element is the two-step confirmation flow and dry-run-first workflow, which are behavioral essentials for a destructive deployment tool, even though the schema hints at them.

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

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

Schema description coverage is 100%, so every parameter is already well documented in the schema (including the important 'yes' confirmation semantics). The description adds no parameter-level meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Deploy project files to a remote server') plus the credential source and return shape, so an agent immediately knows this is the mutation/deploy operation. It is clearly distinct from the list/show/test siblings, though it never explicitly contrasts with any of them.

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

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

The description gives no when-to-use/when-not-to-use guidance: it does not mention that a first call with yes=false returns CONFIRMATION_REQUIRED, nor when to prefer dry_run, remote_scan, or zip_deploy. That confirmation workflow exists only in the schema's 'yes' parameter text, not in the description, and force_branch's policy-override risk is unaddressed.

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 are sparse in substance (readOnlyHint=false, idempotentHint=true) and the description carries the real weight: it discloses the auth mechanism (Keychain credentials), the exact local destination pattern (~/.deployctl/downloads/<project>/<environment>/), that the response exposes local_path, that trailing lines are returned inline with secrets redacted, and the two refusal conditions. None of that is recoverable from the annotations and it is consistent with readOnlyHint=false (a local write occurs).

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

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

Three sentences, front-loaded with the action and path example, then destination/return behavior, then the refusal guardrails. No sentence restates the name or the schema, and each clause adds new 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?

There is no output schema, so the description must explain the return — and it does: local_path plus inline tail lines with redaction. Combined with the destination path, credential source, and refusal rules, an agent has everything needed to call it once and interpret the result without a follow-up.

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, but the description earns an increment by tying tail_lines to observable behavior ("the last lines are returned inline") and by surfacing the max_bytes refusal as a semantic consequence rather than just a field. It does not add format or syntax detail for remote_path or environment beyond what the schema already states.

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

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

The description opens with a specific verb and resource ("Download one file ... from the remote server") and immediately scopes it with an example path plus the constraint that directories are refused. The combination of "one file" and the path example makes it unambiguous versus a bulk or directory-listing operation like browse_remote_directories.

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 states the context of use (retrieving a single remote file with Keychain credentials) and gives exclusions in the form of refusals: directories and files over max_bytes. It also names the downstream step (local_path readable with a file tool). What it never states explicitly is how to obtain a valid remote_path — that routing to browse_remote_directories appears only in the parameter schema, not the description.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value by disclosing what the response contains (environments, protocols, credential status) — notably that credential status is exposed, which matters for an agent reasoning about auth readiness.

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

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

A single front-loaded sentence with no filler; every element (projects, environments, protocols, credential status) carries information about the return payload.

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

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

With no output schema, the description appropriately compensates by listing the fields returned. Minor gaps remain — no mention of ordering, whether credentials are masked, or how an empty configuration is represented — but for a zero-param read tool this is largely 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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter discussion is needed or present.

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

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

Specific verb ('List') plus resource ('projects') and it enumerates the content returned: target environments, protocols, and credential status. The word 'all' implicitly contrasts with the singular show_project sibling, but no sibling is named explicitly, so it falls short of full differentiation.

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

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

Usage is only implied — an agent can infer this is the entry point for discovering configured projects before calling show_project or deploy_project, but the description never states when to use it versus those alternatives or any prerequisites.

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 this is a non-destructive, idempotent, closed-world write. The description adds the non-obvious fact that the write lands in projects.yaml rather than creating a directory on the remote host — a real clarification for an agent that might otherwise assume remote filesystem effect. It stops short of noting overwrite behavior on an already-set path.

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?

One sentence, front-loaded with the action and the field being set, with the persistence target tacked on where it costs nothing. No filler to cut.

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?

Enough to call it correctly, but silent on the behavior an agent would want before mutating shared config: whether an existing value is overwritten, whether the remote path must already exist, and what the tool returns (no output schema). Reasonable but with clear gaps for a config-mutation 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% and every parameter carries its own example-laden description, so the schema does the heavy lifting. The description only restates that project + environment identify the target and remote_path is the value, adding no format or validation detail 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?

Specific verb plus resource: "Configure the remote deployment destination directory (remote_path)" scoped to a project and environment, and it even names the persistence target (projects.yaml). That distinguishes it from browse_remote_directories and download_remote_file, though it never explicitly separates itself from the similarly named set_target_option.

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

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

Usage is only implied: an agent can infer this is a setup step before deploy_project, but the description never says when to call it, whether a prior listing via browse_remote_directories is expected, or what happens if the project/environment doesn't already exist.

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 idempotentHint=true, destructiveHint=false and openWorldHint=false, and the description goes beyond them by explaining what each option value means, including that delete_missing=owned is the default and only removes files deployctl itself deployed. It stops short of saying when the setting takes effect (next deploy vs. immediately) or whether values are validated, which is the one behavioral gap left for a config mutation.

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

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

Two sentences: the action and scope first, then a compact option-to-type mapping. No filler, and the densest information (the option list) is placed after the statement of 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?

With no output schema the description must carry the load, and it does for purpose, target, storage location and value semantics. The remaining omission is what happens after the write (does the change require a subsequent deploy_project to take effect, what does the call return), which is a meaningful but modest gap for a simple config setter.

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, and the description earns above that by adding semantics the enum alone lacks: delete_missing's three levels with their default, allowed_branches as branch names, post_deploy_delete as file patterns, and the type of each other option. It adds nothing for project, environment or value, but the schema already covers those.

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

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

Names a specific verb and resource ("Change one safety/behaviour option of an existing deployment target") and pins the storage location (projects.yaml), which no sibling touches. It is clearly distinguishable from list_projects, deploy_project, show_project and set_remote_path.

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

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

The phrase "an existing deployment target" implies the project must already exist, and "Change one ... option" implies one option per call. But there is no explicit when-to-use/when-not, no mention that this does not deploy, and no pointer to deploy_project to apply the change. Usage is inferred rather than stated.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuine behavioral fact: passwords in the returned configuration are protected/redacted, which warns the agent not to expect secrets. It doesn't say whether they are omitted, masked, or otherwise altered, and says nothing about the shape or size of the returned config.

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

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

Two short sentences, front-loaded with the action and resource, and the redaction warning in the second sentence is directly relevant. Nothing is padded or repeated from the schema.

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

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

For a simple read-only tool with full schema coverage and complete annotations, the basics are covered. However, there is no output schema, and the description doesn't indicate what 'deployment configuration' actually contains or how it varies by environment, leaving the agent guessing at the 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?

Schema description coverage is 100%, with both 'project' and 'environment' (including its production default) documented in the schema. The description adds no meaning beyond that, so the baseline of 3 applies.

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

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

It states a specific verb and resource ('Inspect project deployment configuration'), which clearly separates it from siblings like list_projects and deploy_project. It never names a sibling explicitly, so the differentiation is inferred from wording rather than stated.

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 use case is implied: fetch the deployment configuration of one project rather than listing projects or deploying. There is no explicit when-to-use/when-not guidance, no mention of the environment parameter, and no routing to an alternative tool for adjacent needs such as test_connection or set_target_option.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds two genuinely new facts: connections use stored credentials (no auth flow needed) and no deployment is performed, which is exactly the context an agent needs to trust it as a dry-run check.

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

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

A single front-loaded sentence with no filler; the non-deploying, credential-using nature is stated immediately.

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 two-parameter read-only probe with rich annotations, most of what's needed is present. However, there is no output schema and the description never says what a test returns (pass/fail, error detail, latency), which is the key cognitive gap for a connectivity test 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%, so both `project` and `environment` are already documented with defaults. The description adds no syntax, format, or environment-name conventions beyond the schema, so baseline 3 applies.

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

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

Names a specific verb (test connectivity) and resource (remote server target), and the phrase 'without deploying' implicitly separates it from the sibling deploy_project. It stops short of naming any sibling tool explicitly, so differentiation is somewhat inferential.

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?

'Without deploying' hints at when to prefer this over deploy_project, but there is no explicit guidance on prerequisites, when to run it (pre-deploy validation?), or what to do with the result. Usage is implied rather than stated.

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