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

With no annotations provided, the description fully carries the behavioral disclosure burden. It explicitly states the action is permanent, unrecoverable, and destroys all data, config, and volumes — critical behavioral traits for a destructive tool. This is exemplary 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 two short sentences with every word earning its place: the first states the action and scope, the second emphasizes irreversibility. It is front-loaded and avoids any 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 one-parameter destructive action, the description covers the essential context: the operation is irreversible and destroys related resources. No output schema exists, and for a delete operation a success/failure response is generally assumed. The tool is simple enough that nothing critical is missing.

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

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

The input schema already describes appId as 'The numeric ID of the app to delete' with 100% coverage, so the description adds nothing beyond that. The baseline of 3 applies because the schema adequately documents the only parameter.

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

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

The description states a specific verb ('delete') and resource ('an app and all its resources'), which clearly distinguishes it from sibling tools like pier_stop_app or pier_rename_app. The phrase 'permanently delete' reinforces the destructive scope and leaves no doubt 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?

The description conveys clear context: use this when you intend to permanently delete an app and its resources. It does not explicitly list alternatives or when-not-to-use scenarios, but the 'UNRECOVERABLE' warning effectively signals that this is for final removal, not for transient operations.

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

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

With no annotations, the description carries the burden of behavior disclosure. It does state that the container is rebuilt and restarted from Git, Dockerfile, Compose, or image sources. However, it omits potential side effects like downtime, whether the operation is asynchronous, or whether existing runtime data is preserved.

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

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

The description is two short front-loaded sentences with no filler. The first sentence states the purpose, and the second earns its place by clarifying the rebuild/restart behavior and supported source types.

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 one-parameter tool, the description covers the core action and behavior well. It is missing details about return values, asynchronous completion, and potential deployment failures, but those are not critical for selecting and invoking this 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?

The schema already fully describes the only parameter, appId, at 100% coverage. The description does not add extra parameter constraints, formatting rules, or relationships beyond what the schema provides.

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 ('Trigger a new deployment for an app') and adds behavioral specificity by explaining that it rebuilds and restarts the container from a configured source. This clearly distinguishes it from siblings like pier_start_or_restart_app, because rebuilding from source is the defining deployment action.

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

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

No guidance is given about when to use this tool versus alternatives such as pier_start_or_restart_app. The word 'deployment' implies some usage context, but there is no explicit when-to-use, exclusions, or mention of 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?

No annotations are provided, so the description carries the safety burden. The wording 'Check the current status' clearly indicates an observation/read operation rather than a state change, and it discloses the kind of information returned. It does not detail error behavior or authentication, but those are less critical for this simple read 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?

Two short sentences with the core behavior front-loaded and the usage guidance appended. Every sentence carries useful information with no redundancy or 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 one-parameter read operation with no output schema, the description sufficiently conveys the result content and use cases. Minor omissions such as exact response shape or error conditions do not undermine the agent's ability to 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?

The only parameter, appId, is already fully documented in the schema as 'The numeric ID of the app.' The description only refers generically to 'an app' and adds no additional parameter-level semantics, 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?

States a specific read verb ('Check the current status') and resource ('an app'), and enumerates the returned content: 'whether it is running, stopped, or deploying, plus its public endpoints.' This clearly differentiates it from mutation, log, and metric sibling tools.

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

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

Explicitly says when to use it: 'Use this to health-check an app or discover its URLs.' It does not name exclusions or alternatives, but the intended context is unambiguous.

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 alone must disclose behavioral traits. 'Fetch logs' implies a read-only operation, but the description does not confirm that there are no side effects, what the output format is, or how errors like missing containers are handled. The burden is not fully met.

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 one short, front-loaded sentence that states the core action immediately. It is concise, though the 'Requires the container ID' clause adds little beyond the schema's required field.

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 tool, the combination of description and schema is sufficient to make a call. However, with no output schema and no annotations, the description could usefully mention the expected return payload, log format, or behavior for invalid container IDs to be fully 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 100%, so the input schema already documents both containerId and tail. The description adds no additional parameter semantics beyond restating that the container ID is required, which is already explicit in the schema. Baseline 3 applies.

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

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

The description uses a specific verb and resource ('Fetch logs from a specific Docker container'), making the primary action clear. It distinguishes itself from the sibling pier_get_logs by explicitly targeting container-level logs, though it does not name that alternative.

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 'specific Docker container' implies when the tool is appropriate, and 'Requires the container ID' gives the key prerequisite. However, there is no explicit guidance about when to choose this over pier_get_logs or how it relates to the other pier_* 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?

No annotations are provided, so the description carries the safety burden. 'Read' clearly signals a non-mutating operation, and 'full set' communicates the expected response scope. It does not detail return format or error behavior, but for a simple getter this is sufficient disclosure.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes: 'Read' states the action, 'full set' states the scope, and 'environment variables for an app' states the resource.

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 one required integer parameter, full schema coverage, and no output schema, the description is nearly complete. It identifies the target, the read-only nature, and the full-set result. A note about the exact return structure or error behavior would be extra but is not essential for correct selection and invocation.

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

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

Schema description coverage is 100%, and the appId parameter is already documented as 'The numeric ID of the app.' The description adds no additional meaning about the parameter beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Read'), a specific resource ('environment variables'), and a clear scope ('full set for an app'). It distinguishes itself from siblings like pier_set_env_vars and pier_update_env_var through the read-only action and full-collection 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 use case is implied: use this tool when you need to read all environment variables for an app. However, there is no explicit when-not-to-use guidance, named alternatives, or mention of using set/update when modification is needed.

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 behavioral burden. 'Fetch' implies a read-only operation, but the description does not explicitly state non-mutating behavior, default tail behavior, output shape, or what happens when no logs exist. It is minimal rather than misleading.

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

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

The description is two short sentences with no filler. The primary purpose is front-loaded and the optional limit is stated compactly.

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?

This is a simple two-parameter read tool, so the description is minimally adequate. However, it lacks return-format expectations and does not clarify the relationship with pier_get_container_logs, which makes the context incomplete for optimal tool selection.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description restates the optional tail limit but adds no deeper semantic details such as default values, formatting, or constraints 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 states a specific action ('Fetch') and resource ('recent deployment logs for an app'), making the core purpose clear. It does not explicitly contrast with the similar-sounding sibling pier_get_container_logs, but 'deployment logs' adds enough specificity to distinguish the domain.

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

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

No guidance is given about when to use this tool versus alternatives. Given siblings such as pier_get_container_logs, an agent would benefit from explicit direction on when deployment logs are the right source. No exclusions, preconditions, or fallback guidance are provided.

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 behavioral burden. The word 'Get' implies a read-only retrieval, and the metrics list conveys scope. However, it does not disclose output format, units, sampling behavior, or any operational caveats, so transparency is adequate but incomplete.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes meaning, and the scope is communicated compactly.

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 covers the essential selection and invocation context by naming the measured resources. It stops short of specifying the response shape or any access prerequisites, which would make it fully complete for all use cases.

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, and the schema is an empty object, so there are no parameter meanings to document. The description provides all relevant context by naming the metric categories. This matches the baseline 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?

The description uses a precise verb ('Get') and a specific resource ('server-level metrics') and enumerates exactly what is covered: CPU, RAM, disk, and network usage. This clearly distinguishes it from sibling tools that target apps or containers.

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 'server-level metrics' implicitly signals when to use this tool versus the app-level and container-level sibling tools. It does not explicitly state when not to use it or name an alternative, but the context is clear enough for 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?

With no annotations, the description carries the full behavioral burden. It discloses the return format and that it is a listing operation, but it doesn't explicitly state that it is read-only or explain pagination behavior despite having page/pageSize parameters. This is adequate but not deeply transparent.

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

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

Three short sentences, each adding necessary information: the operation, the return shape, and the workflow guidance for discovering IDs. There is no filler or 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?

For a simple list tool with no output schema and no annotations, the description covers the core purpose, return structure, and usage context. It could be slightly more complete by noting that page/pageSize may be needed to retrieve 'all' apps when there are many, but the essentials are present.

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

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

Schema description coverage is 100%, with both page and pageSize documented in the schema. The description adds no additional parameter-level meaning beyond restating that this lists apps/services, so the baseline score 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 states a specific verb ('List'), the exact resource ('apps/services deployed on the Pier server'), and the return shape ('array of services with IDs, names, status, and URLs'). It clearly differentiates from sibling tools by framing this as the discovery operation for app IDs used by all other 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 explicitly tells the agent when to use this tool: call it first to discover app IDs, then use those IDs for other operations. This gives practical routing guidance that distinguishes it from all the mutation and status 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 provided, the description carries the behavioral burden. It transparently communicates a read-only listing operation and clarifies that the result includes both Pier-managed and standalone containers, so an agent can infer there are no destructive side effects. It does not mention access requirements, but those are not material for a zero-parameter list.

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

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

The description is a single front-loaded sentence that states the action and scope without any filler. It earns its place by distinguishing the container scope from sibling application-focused tools.

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 listing tool, the description is essentially complete: it names the resource, the scope, and the inclusion criteria. It stops slightly short of describing the output format, but that omission is minor for such a straightforward list operation.

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 accepts zero parameters, so the description does not need to explain parameter meanings. The baseline of 4 applies because there is nothing the schema must document.

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 ('List') and a specific resource ('all Docker containers on the server'), and explicitly scopes the result to include both Pier-managed and standalone containers. This clearly differentiates it from the sibling pier_list_apps, which targets applications rather than containers.

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 intended use is implied: use this when you need an inventory of Docker containers on the server. However, there is no explicit guidance about when not to use it or which sibling to prefer (e.g., pier_list_apps when only Pier applications are relevant).

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 of disclosing behavioral traits. It only states the action without mentioning whether the change is persistent, whether it affects app identity or runtime state, what permissions are required, or what happens on 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 a single, front-loaded sentence with no wasted words. It communicates the core operation immediately and is appropriately sized for such a simple 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 operation is simple and the parameter schema is complete, but with no annotations and no output schema, the description leaves gaps around behavioral expectations and result handling. It is minimally viable but not richly contextual.

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

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

Schema description coverage is 100%, so both parameters (appId and name) are already documented in the schema. The description adds no additional parameter-level meaning, so the baseline score 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 the specific verb 'Change' with the precise resource 'display name of an app,' which cleanly identifies the operation. It is clearly distinct from the sibling tools, which handle listing, status, lifecycle, environment variables, logs, and metrics.

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 intended use is implied: an agent should invoke this tool when it needs to change an app's display name. However, it does not explicitly state when not to use it, mention prerequisites, or describe any alternatives, leaving usage context to inference.

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 and delivers: 'Any existing variables not included in the new array will be deleted' explicitly discloses the destructive replace semantics. This is the key behavioral trait an agent needs 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?

Two sentences, each earning its place: the first states the core operation, the second exposes destructive behavior and names the lighter alternative. No filler, well 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?

For a simple two-parameter tool with no output schema, everything needed to call it correctly is present: what it does, the destructive scope, and the appropriate alternative. No meaningful information gap remains.

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 valuable semantic context by clarifying that envVars is the complete replacement set, tying it to the deletion behavior rather than just listing it as 'Array of {name, value} variables'.

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

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

The description states a specific verb and resource: 'Replace the entire environment variable set for an app.' It also explicitly contrasts with 'update_env_var', making sibling differentiation clear without opening either schema.

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

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

It explicitly says when to use this tool (when replacing the full set) and when not: 'For a single variable change, use update_env_var instead.' This directly routes the agent to the correct alternative.

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

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

With no annotations present, the description carries the burden of behavioral disclosure. It importantly warns that the tool 'Recreates the container — all non-volume state is lost,' which is critical for a delete-prone operation. It stops short of describing outcomes or response behavior, but covers the main risk.

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 deliver the core action, the key side effect, and the primary usage context with no filler or repetition. The most important warning is front-loaded for the agent to notice.

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 one parameter and no output schema, the description provides everything needed to call it correctly: what it does, when to use it, and the destructive consequence. The missing return-value details are not necessary 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?

The schema already documents appId as 'The numeric ID of the app' with 100% coverage. The description adds no extra parameter meaning, so the baseline score 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 and resource: 'Start a stopped app, or restart a running one.' It clearly conveys the dual action and distinguishes itself from siblings like pier_stop_app and pier_delete_app.

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

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

The description explicitly tells when to use the tool: 'Use after ANY config change (env vars, ports, image, command) for the change to take effect.' It does not name specific alternatives, but it gives clear situational 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?

With no annotations, the description carries the full burden and does well: it discloses that the container is removed, persistent volumes are preserved, and the operation is reversible by restart. It stops short of stating that non-persistent container filesystem data is lost or describing the resulting app status, but the core destructive effect is clear.

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

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

Three short, information-dense sentences with no filler. The primary effect is front-loaded, followed by the persistence caveat and then the recovery path.

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 one-parameter shutdown tool, the description covers the essential context: what happens, what persists, and how to undo it. It could mention loss of non-persistent container data and return-value behavior, but neither is necessary 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?

The schema already describes appId with 100% coverage, and the description adds no parameter-specific meaning beyond that. This matches the baseline for fully schema-documented 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?

Clearly states the action ('Stop an app and remove its container') and differentiates from permanent deletion by noting persistent volumes are kept and teardown is temporary. An agent can distinguish this from pier_delete_app and pier_start_or_restart_app without opening schemas.

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 names start_or_restart_app as the recovery path and frames the operation as a temporary teardown, giving clear context for when to use it. It doesn't explicitly contrast with pier_delete_app or state when not to use it, but the persistent-volume/temporary framing is sufficient 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?

No annotations are provided, so the description carries the full behavioral burden. It does add useful behavioral context: 'Add or update' implies mutation and idempotent overwrite, and 'without affecting other variables' is a strong guarantee. However, it does not disclose side effects (e.g., whether changes trigger a restart), permissions, or what the response is, which leaves notable gaps for a write 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?

Two sentences, zero filler. The action and scope are front-loaded in the first sentence, and the usage routing is in the second. 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 mutation tool with fully documented parameters, an explicit behavioral guarantee, and clear sibling differentiation, the description is nearly complete. It lacks an output schema and does not mention return values or prerequisites, but given the tool's simplicity, those omissions are less critical than for more complex tools.

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 all three parameters at 100% coverage, so the description does not need to add parameter details. The tool description adds almost no parameter-specific meaning beyond the schema, 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 states the specific action 'Add or update a single environment variable' with a clear resource and scope. It explicitly differentiates from the sibling pier_set_env_vars by emphasizing 'single' and 'without affecting other variables', so an agent can distinguish it immediately.

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

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

It explicitly states 'Preferred over set_env_vars for individual changes', naming the alternative and the condition for choosing this tool. This is rare and very helpful.

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