Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Ploi.io MCP Server list my servers"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for Ploi.io account management using the Ploi API.
It ships with two transports that share the same tools:
stdio — run locally, launched by your MCP client. Authenticates with a
PLOI_API_TOKEN from the environment (src/index.ts).
Cloudflare Worker — remote, multi-tenant Streamable HTTP server. Each
caller supplies their own Ploi token as Authorization: Bearer <token>;
nothing is stored on the Worker (src/worker.ts). See
Deploy to Cloudflare and
Use with Poke.
npm install
npm run buildCreate a Ploi API token from your Ploi profile, then configure your MCP client to launch this server with the token in the environment:
{
"mcpServers": {
"ploi": {
"command": "node",
"args": ["/path/to/ploi-mcp-server/dist/index.js"],
"env": {
"PLOI_API_TOKEN": "your-ploi-api-token"
}
}
}
}Optional environment variables:
PLOI_API_BASE_URL: override the API base URL. Defaults to
https://ploi.io/api.
PLOI_USER_AGENT: override the user agent sent to Ploi. Defaults to
ploi-mcp-server/1.0.0.
Related MCP server: Coolify MCP Server
The Worker exposes the same tools over the MCP Streamable HTTP transport at
/mcp (legacy SSE at /sse), backed by a Durable Object via the
agents SDK. GET / is a health
check.
Authentication is multi-tenant and pass-through. The Worker stores no
Ploi credentials. Every request must carry the caller's own Ploi token as
Authorization: Bearer <token>; that token is bound to the MCP session and used
for all Ploi API calls in that session. Requests without a bearer token get
401.
npm install
npx wrangler login
npm run deploy # deploys to https://ploi-mcp-server.<subdomain>.workers.devNo secrets to configure. Optional PLOI_API_BASE_URL / PLOI_USER_AGENT
overrides can be added under vars in wrangler.jsonc.
npm run dev # local worker at http://localhost:8787Pass a token per request, e.g.:
curl -s http://localhost:8787/health
curl -s -X POST http://localhost:8787/mcp \
-H "Authorization: Bearer <your-ploi-token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"dev","version":"0"}}}'After editing wrangler.jsonc, run npm run cf-typegen (wrangler types) and
typecheck the Worker with npm run typecheck:worker.
Poke sends the integration's API key as
Authorization: Bearer <key> on every request — so each user simply pastes
their own Ploi API token as the key, and the Worker uses it for that user.
Deploy the Worker (above) and note its URL.
In Poke, add an MCP integration:
URL: https://ploi-mcp-server.<subdomain>.workers.dev/mcp
API Key: the user's Ploi API token (from the Ploi profile page)
Or via CLI:
npx poke@latest mcp add \
https://ploi-mcp-server.<subdomain>.workers.dev/mcp \
-n "Ploi" -k "<user-ploi-api-token>"Each Poke user's token only ever touches their own session; the Worker keeps no copy. If a request arrives without a token, or the token is rejected by Ploi, the corresponding tool call returns an error.
ploi_list_servers
ploi_get_server
ploi_create_server
ploi_create_custom_server
ploi_start_custom_server_installation
ploi_update_server
ploi_restart_server
ploi_delete_server
ploi_list_sites
ploi_get_site
ploi_create_site
ploi_update_site
ploi_delete_site
ploi_deploy_site
ploi_get_site_nginx_configuration
ploi_update_site_nginx_configuration
ploi_list_databases
ploi_get_database
ploi_duplicate_database
ploi_forget_database
ploi_list_containers
ploi_get_container
ploi_create_container
ploi_update_container
ploi_start_container
ploi_stop_container
ploi_restart_container
ploi_delete_container
Ploi exposes documented up and down endpoints for Docker containers. The
restart tool queues a shutdown followed by a startup using those endpoints.
ploi_list_server_providers
ploi_get_server_provider
ploi_list_backup_configurations
ploi_get_ip_addresses
Destructive tools require a confirm: true argument.
Create a Docker application container on a Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Container name. Must be unique per server. | |
| server_id | Yes | Ploi server ID. | |
| deploy_script | No | Docker Compose YAML. Ploi provides a default when omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only=false (mutation) and not destructive or idempotent. The description adds no new behavioral context such as side effects (e.g., containers may fail if name not unique), auth requirements, or process details. It minimally confirms creation without enriching the annotation information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence with no wasted words. It is appropriately front-loaded and efficient for its purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and full schema coverage, the description is nearly complete. However, it omits explicit mention that the 'server_id' parameter is required and that the container is created on that specific server, which is implied but not stated. Still, for a straightforward creation tool, it is adequate.
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%: each parameter has a clear description. The tool's description adds no additional meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create'), the resource ('Docker application container'), and the context ('on a Ploi server'). It effectively distinguishes this tool from sibling operations like update, delete, or list 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 description provides no guidance on when to use this tool versus alternatives (e.g., when to use update or delete). No prerequisites, exclusions, or comparison with other create tools are mentioned, leaving the agent to infer context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a custom server record and return the SSH command/start URL required to begin installation.
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | Public IPv4 address of the custom server. | |
| name | Yes | Server name. | |
| type | No | Server type to install. | server |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value by stating the return value (SSH command/start URL), but beyond the annotations (non-readonly, non-destructive), it does not disclose additional behavioral traits such as prerequisites, side effects, or authentication requirements.
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?
Single sentence of 15 words, efficiently communicates the core purpose and return value with no unnecessary 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 creation tool with 3 parameters and no output schema, the description provides essential info (return value), though it could mention output structure or uniqueness constraints.
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 description does not add new meaning to parameters. It does not explain parameter format or constraints 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 clearly states the action ('Create') and the resource ('custom server record'), and specifies the return value (SSH command/start URL). It effectively distinguishes from siblings like ploi_create_server and ploi_start_custom_server_installation.
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 on when to use this tool vs alternatives. With siblings like ploi_create_server and ploi_start_custom_server_installation, the description should provide context on when to choose custom server creation over other options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new provider-backed Ploi server. Use account provider tools first to discover valid credentials, plans, and regions.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Server name. | |
| plan | Yes | Provider plan ID. | |
| type | No | Server type to install. | server |
| region | Yes | Provider region ID. | |
| credential | Yes | Server provider credential ID. | |
| php_version | No | PHP version to install, for example 8.4. | |
| webhook_url | No | Webhook called when server installation completes. | |
| database_type | No | Database type to install. | mysql |
| webserver_type | No | Webserver type to install. | nginx |
| install_monitoring | No | Whether to install monitoring. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-readOnly, non-destructive, non-idempotent behavior. The description adds that it creates a server but no further behavioral details (e.g., async completion, return values). Given annotation coverage, the description provides adequate but minimal added 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 consists of two concise sentences with no extraneous information. It is well-structured and front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, no output schema), the description covers the primary action and prerequisite steps. It does not explain return values or async behavior, but for a creation tool with sibling context, it is reasonably 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?
All 10 parameters have descriptions in the input schema (100% coverage), so the baseline is 3. The description does not add any parameter-specific information beyond the schema, only general guidance about discovering credentials, plans, and regions.
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 'Create a new provider-backed Ploi server', specifying the verb and resource. It distinguishes from the sibling 'ploi_create_custom_server' by emphasizing 'provider-backed'.
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 advises to 'Use account provider tools first to discover valid credentials, plans, and regions', providing prerequisite guidance. It does not explicitly state when not to use this tool or mention alternatives, but the context implies the custom server creation tool is an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new site on a Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| server_id | Yes | Ploi server ID. | |
| root_domain | Yes | Root domain for the site. | |
| system_user | No | System user that owns the site files. | |
| webhook_url | No | Webhook called when site creation completes. | |
| project_root | No | Project root path. | |
| project_type | No | Application project type. | |
| web_directory | No | Web directory path. | /public |
| webserver_template | No | Webserver template ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false), non-destructive, non-idempotent. The description aligns ('Create') but adds no new behavioral context (e.g., auth needs, rate limits, conflict behavior). With annotations present, the description is adequate but not enhanced.
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 sentence of 9 words, front-loaded and free of redundancy. Every word is necessary and concise.
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 creation tool with 8 parameters and no output schema, the description is too sparse. It omits prerequisites (e.g., server must exist), return value hints, and potential side effects, leaving the agent with insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters have descriptions. The description does not add extra meaning beyond what the schema provides, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create a new site on a Ploi server,' using a specific verb ('Create') and resource ('site') in a clear context. It distinguishes well from sibling tools like ploi_list_sites, ploi_get_site, etc.
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 no guidance on when to use this tool versus alternatives, such as ploi_create_server or ploi_deploy_site. The agent receives no when/when-not advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a Docker container from a Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | Must be true to confirm this destructive operation. | |
| server_id | Yes | Ploi server ID. | |
| container_id | Yes | Ploi Docker container ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description's statement 'Delete' is consistent. The confirm parameter is a safeguard but is not mentioned in the description; its significance is only apparent from the schema. No additional behavioral traits are disclosed beyond what annotations provide.
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 concise sentence, well-structured and front-loaded. However, it could include the critical confirm requirement without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with 3 required parameters, the description is too minimal. It omits the confirm parameter's role, does not describe return behavior (or lack thereof), and provides no reassurance or warning beyond the annotation. The agent is left to infer important details from the schema alone.
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 each parameter is adequately described in the schema. The description adds no extra meaning or context about the parameters (e.g., the purpose of confirm, how to obtain server_id or container_id).
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 (Delete), the resource (Docker container), and the scope (from a Ploi server). It unambiguously distinguishes from sibling tools like ploi_create_container or ploi_list_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?
No guidance is given about when to use this tool versus alternatives, nor any prerequisites or conditions. The description merely states the action without further context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a Ploi server. This is irreversible and removes associated data.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | Must be true to confirm this destructive operation. | |
| server_id | Yes | Ploi server ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description reinforces it with 'irreversible' and adds detail about associated data removal, but does not disclose additional traits like authorization requirements or side effects beyond what annotations imply.
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 concise sentences with no fluff. Information is front-loaded and 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?
For a simple destructive operation with two parameters and no output schema, the description covers the essential purpose and irreversibility. It is mostly complete but could mention typical return values.
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 adds no extra meaning or usage context for the 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?
The description clearly states the tool's action ('Delete a Ploi server') and specifies irreversibility and removal of associated data. It is distinct from sibling tools like ploi_delete_site or ploi_delete_container.
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, when not to, or any prerequisites. The description lacks contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a site from a Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | Must be true to confirm this destructive operation. | |
| site_id | Yes | Ploi site ID. | |
| server_id | Yes | Ploi server ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint: true. The description adds 'Delete' and the confirm parameter reinforces the destructive nature. No contradiction, but lacks additional details like irreversible effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is clear and free of unnecessary words. 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?
Given the destructive nature and confirm parameter, the description could mention irreversibility or success indication. However, it is adequate for a straightforward delete operation with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The tool description adds no extra semantic value beyond what the input schema already provides, so 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 'Delete' and the resource 'site from a Ploi server', clearly distinguishing it from sibling tools like ploi_create_site or ploi_update_site.
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 does not explicitly state when to use or avoid this tool, but the context (destructiveHint annotation and required confirm parameter) implies guarded usage. No alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger or schedule a deployment using the site's configured deploy script.
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes | Ploi site ID. | |
| scheduled | No | Optional scheduled datetime, for example 2023-01-01 10:00. | |
| server_id | Yes | Ploi server ID. | |
| variables | No | Variables to pass to the deploy script. Keys become uppercased environment variables. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false) with non-destructive intent. The description adds context about using the 'configured deploy script' and scheduling, but does not disclose potential side effects, async behavior, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the tool's action and key constraints, with no superfluous words.
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 should clarify the return value (e.g., deployment status or ID) or whether the operation is synchronous. Its absence leaves a notable gap for an agent invoking deployment.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 4 parameters. The description does not add additional parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool triggers or schedules a deployment using the site's configured deploy script, which is a specific verb-resource pair. It distinguishes itself from sibling tools like ploi_list_sites or ploi_restart_server.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for deploying a site, but does not explicitly state when not to use or mention alternatives. Since no other sibling tool handles deployments, the guidance is acceptable but minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clone an existing database to a new database on the same server.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for the new database. | |
| user | No | Optional username for the new database user. | |
| password | No | Optional password for the new database user. | |
| server_id | Yes | Ploi server ID. | |
| database_id | Yes | Ploi database ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is not read-only, not idempotent, and not destructive. The description adds that cloning occurs on the same server, but no additional details (e.g., impact on existing database, time to complete) are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that clearly communicates the tool's action without any wasted words.
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 should hint at return behavior (e.g., returns new database details or success). It also lacks prerequisites (e.g., existing server and database). For a mutation tool with 5 parameters, this is insufficient.
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 description does not add significant meaning beyond the parameter names. The description implies database_id identifies the source but does not elaborate on the new database's name or optional user/password.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'clone' and the resource 'database', specifying the action and the scope ('on the same server'). It distinguishes from list and retrieval tools among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for cloning databases on the same server but provides no explicit guidance on when to use vs. alternatives (e.g., if a cross-server clone is needed) or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a database from Ploi records without deleting it from the server.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | Must be true to confirm this destructive operation. | |
| server_id | Yes | Ploi server ID. | |
| database_id | Yes | Ploi database ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructive hint, but the description adds critical behavioral context: the database is not deleted from the server. This goes beyond what annotations provide, making agent behavior more predictable.
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 concise sentence with no redundant words. It is front-loaded with the key action and nuance, making it 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?
For a simple action with no output schema, the description covers the core behavior and key exception (no server deletion). It does not mention prerequisites or error conditions, but given the low complexity and annotation coverage, it is sufficiently 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 has 100% description coverage for all three parameters, including the confirm parameter. The tool description does not add any parameter-level details, so it meets the baseline without exceeding it.
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 (remove) and resource (database), and crucially distinguishes it from a potentially destructive delete by specifying 'without deleting it from the server.' This makes the purpose unambiguous and distinct from 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?
The description implies the use case (removing Ploi records while keeping server data) but does not explicitly state when to use vs. alternatives or provide any exclusion criteria. Given the sibling set includes only one other database tool (ploi_duplicate_database), the guidance is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve details for a single Docker container on a Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| server_id | Yes | Ploi server ID. | |
| container_id | Yes | Ploi Docker container ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and no destructive action. Description adds 'Retrieve details' which aligns but provides no additional behavioral context beyond what annotations offer.
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?
Single sentence of 12 words, no wasted words, purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with two well-documented parameters and no output schema, the description is adequate. Could optionally mention what details are returned, but not necessary.
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% for both parameters, so baseline 3. Description does not add additional meaning 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?
Description clearly states verb 'Retrieve', resource 'details for a single Docker container', and context 'on a Ploi server'. Distinguishes from sibling tools like ploi_list_containers (list all) and ploi_create_container.
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 implied from the purpose (retrieve a specific container), but no explicit guidance on when not to use it or alternatives among the many container-related siblings (list, create, update, delete, etc.).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve details for a single database on a Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| server_id | Yes | Ploi server ID. | |
| database_id | Yes | Ploi database ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which fully cover the safety and behavioral profile. The description adds minimal value beyond confirming the read-only retrieval nature, so it is adequate but not enriched.
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 10-word sentence that is front-loaded and efficient. Every word adds value, with no wasted or redundant phrasing.
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 simple tool with two fully documented parameters, rich annotations, and no output schema, the description adequately covers the tool's purpose and usage context. The agent can understand what the tool does without additional details.
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 provides 100% coverage with descriptions for both parameters (server_id and database_id). The description does not add further semantics beyond what the schema already provides, so baseline score 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 'Retrieve details for a single database on a Ploi server' uses a specific verb ('retrieve'), resource ('details for a single database'), and context ('on a Ploi server'), clearly distinguishing it from sibling tools like ploi_list_databases or ploi_duplicate_database.
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 no guidance on when to use this tool versus alternatives, such as ploi_list_databases or ploi_duplicate_database. It lacks explicit when-to-use, when-not-to-use, or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve Ploi IP addresses for allow-listing workers and uptime checks.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context about the intended use but does not disclose additional behavioral traits beyond what annotations provide.
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, concise sentence that front-loads the action (Retrieve) and resource (Ploi IP addresses). Every word earns its place with zero waste.
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 tool with no parameters and no output schema, the description is sufficient. It explains the purpose and use case, though it could optionally specify output format. Overall complete enough.
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?
There are 0 parameters, so no additional parameter information is needed from the description. The description adds no param info, but baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves Ploi IP addresses for a specific purpose (allow-listing workers and uptime checks), distinguishing it from all sibling tools which deal with servers, sites, databases, etc.
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 mentions usage context (allow-listing workers and uptime checks), but does not provide explicit when-not-to-use or alternative tools. However, the unique purpose makes it clear when to invoke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve details for a single Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| server_id | Yes | Ploi server ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, indicating safe, idempotent read. Description adds no extra behavioral context (e.g., response structure). With rich annotations, bar is lower; no contradiction, but minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is one sentence, no wasted words. Could benefit from slightly more detail (e.g., what 'details' entails), but overall efficient and front-loaded with key 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?
Given low complexity (1 param, no output schema, rich annotations), description is minimally complete. It covers the core action but lacks detail on return format or what fields are included, which could aid agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter (server_id). Description does not add any meaning beyond the schema's description. Baseline 3 is appropriate since schema already documents the parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves details for a single Ploi server, using a specific verb and resource. It distinguishes from sibling tools like ploi_list_servers (list all) and ploi_get_site (different resource), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives, but the context of sibling tools (e.g., ploi_list_servers for listing all servers) implies this tool is for a specific server. Missing explicit exclusions or preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a server provider credential, including available plans and regions.
| Name | Required | Description | Default |
|---|---|---|---|
| provider_id | Yes | Ploi server provider ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context about included plans and regions but no additional behavioral disclosures.
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 of 10 words, no fluff, directly states purpose and included 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 read tool with one parameter and no output schema, the description covers the basic return content. Missing explanation of what a 'server provider credential' is, but adequate given low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already provides a clear description for the one parameter (provider_id). Tool description adds no extra meaning beyond that, so baseline 3.
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 (retrieve), resource (server provider credential), and what is included (plans and regions). It distinguishes from sibling tools like ploi_list_server_providers and ploi_get_server.
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 on when to use this tool versus alternatives. Does not mention when to use it vs ploi_list_server_providers or other read tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve details for a single site on a Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes | Ploi site ID. | |
| server_id | Yes | Ploi server ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds no additional behavioral context beyond 'retrieve details', which aligns with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence with no unnecessary words. Efficiently communicates the tool's 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?
Simple retrieval tool; description covers the purpose. No output schema, but openWorldHint suggests variable response. Minor gap: no mention of return fields, but sufficient for its 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?
Schema descriptions cover both parameters with basic info ('Ploi site ID.', 'Ploi server ID.'). Description does not add further meaning, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'retrieve', resource 'details for a single site', and context 'on a Ploi server'. It differentiates from sibling tools like ploi_list_sites and ploi_create_site.
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 implied: use when you have a specific site_id. No explicit guidance on when to prefer this over ploi_list_sites or other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the NGINX configuration for a Ploi site.
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes | Ploi site ID. | |
| server_id | Yes | Ploi server ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds no behavioral nuance beyond 'Retrieve', which aligns. No extra context on edge cases or response behavior is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words. It is front-loaded and efficient, conveying the essential purpose without 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?
The tool is simple with two integer parameters, and annotations cover safety. The description explains the action but does not explicitly state the return format or contents, which would be helpful given no output schema. However, 'Retrieve' sufficiently implies the output is the configuration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters ('Ploi site ID.', 'Ploi server ID.'). The description does not add further meaning beyond what the schema already provides, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'NGINX configuration for a Ploi site'. This distinguishes it from siblings like 'ploi_get_site' (general site info) and 'ploi_update_site_nginx_configuration' (modification).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when needing NGINX config), but lacks alternatives or exclusions. Among many siblings, there is no guidance on when to prefer this over other site-related tools, such as contrasting with 'ploi_update_site_nginx_configuration'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List backup configurations linked to the authenticated Ploi account.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Pagination page number. | |
| per_page | No | Items per page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety traits. However, it adds no behavioral context beyond the annotations, such as pagination behavior or result format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it is minimally informative. It earns its place but lacks any expansion on usage or results. It is adequate but not exemplary.
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 the tool has only two well-documented parameters and no output schema, the description is minimally sufficient. However, it could include hints about the response structure or filtering capabilities to improve completeness.
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 the schema already describes the 'page' and 'per_page' parameters. The description adds no additional meaning or context for these parameters, so 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 verb 'list' and the resource 'backup configurations', and specifies they are linked to the authenticated account. This is distinct from all sibling tools, which deal with servers, sites, databases, etc.
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 versus alternatives, nor are there any exclusions. While no sibling directly overlaps, the description does not help an agent decide when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a paginated list of Docker containers on a Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Pagination page number. | |
| per_page | No | Items per page. | |
| server_id | Yes | Ploi server ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds only that the result is paginated, which is already implied by pagination parameters. No additional behavioral traits like rate limits or ordering are disclosed.
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 sentence that conveys all essential information without unnecessary words. It is efficiently structured and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with well-documented parameters and annotations, the description is complete enough to invoke correctly. The absence of an output schema is mitigated by the fact that the return is a standard paginated list, and the description mentions that. A minor improvement could be noting the default pagination values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented in the input schema. The tool description adds no extra semantic meaning beyond what the schema provides, meeting the baseline of 3.
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 (retrieve), resource (Docker containers), and scope (on a Ploi server). It also mentions pagination, which distinguishes it from sibling tools like ploi_get_container.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing containers but provides no explicit guidance on when to use this tool versus alternatives like ploi_get_container or ploi_create_container. No when-not-to-use or condition information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a paginated list of databases on a Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Pagination page number. | |
| per_page | No | Items per page. | |
| server_id | Yes | Ploi server ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by specifying pagination behavior, which is not covered by annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is concise and front-loaded with the core purpose. Every word is necessary and there is 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 simple list operation with rich annotations, the description adequately covers the tool's behavior. It mentions pagination, which is key. However, it does not describe the return format (e.g., the structure of database objects), though no output schema exists.
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 each parameter has a description. The tool description adds no additional meaning beyond what the schema already provides for the 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?
The description clearly states the action (Retrieve), resource (paginated list of databases), and scope (on a Ploi server). It effectively distinguishes from siblings like ploi_get_database which retrieves a single database.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: when you need a list of databases. However, it does not explicitly state when not to use it or mention alternatives like ploi_get_database for individual databases, leaving guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List server provider credentials linked to the authenticated Ploi account.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Pagination page number. | |
| per_page | No | Items per page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only and non-destructive. The description adds minimal extra context; it could mention pagination behavior or that credentials are returned.
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?
Single short sentence with no wasted words, but could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with good annotations, the description is adequate. No output schema, but the tool's behavior is straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description does not add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'server provider credentials', and it distinguishes this tool from sibling 'ploi_get_server_provider' which likely retrieves a single provider.
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 on when to use this tool versus alternatives like 'ploi_get_server_provider' or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a paginated list of all servers in the authenticated Ploi account.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Pagination page number. | |
| per_page | No | Items per page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing safety. The description adds behavioral detail about pagination, which is not captured in annotations, enhancing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is concise and includes essential information. Every word adds value, and it is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (list with pagination) and has rich annotations. Although there is no output schema, the description and annotations sufficiently cover what the agent needs to know for correct usage.
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 itself fully documents the parameters. The description adds no further parameter semantics beyond what is in the schema, warranting a baseline score of 3.
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 ('Retrieve a paginated list'), the resource ('all servers'), and the scope ('in the authenticated Ploi account'). This distinguishes it from sibling tools like ploi_get_server (single server) and ploi_create_server (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?
The description implies use for listing all servers in a paginated manner, which differentiates from ploi_get_server (single) and ploi_create_server (creation). However, it does not explicitly state when not to use or provide alternative suggestions, but the context is clear given sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a paginated list of all sites on a Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Pagination page number. | |
| per_page | No | Items per page. | |
| server_id | Yes | Ploi server ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds the 'paginated' aspect, which is minimal additional context. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose. Every word is necessary, and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (listing paginated sites), the combination of schema and annotations covers most needs. The description is sufficient, though it could mention that the output is a list of site objects, but since no output schema is provided, slight detail 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?
Schema description coverage is 100%, with each parameter having a clear description. The tool's description does not add any extra meaning beyond the schema, 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 explicitly states the action ('Retrieve a paginated list') and the resource ('all sites on a Ploi server'), clearly distinguishing it from sibling tools like ploi_list_servers or ploi_get_site.
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 for when to use this tool (to list all sites on a server), but does not explicitly mention when not to use it or alternatives such as ploi_get_site for a single site.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queue a Docker container shutdown followed by startup using Ploi's documented down/up endpoints.
| Name | Required | Description | Default |
|---|---|---|---|
| up_flags | No | Additional docker-compose flags. | |
| server_id | Yes | Ploi server ID. | |
| down_flags | No | Additional docker-compose flags. | |
| container_id | Yes | Ploi Docker container ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, and description adds that it queues two sequential operations (shutdown then startup). This goes beyond annotations by revealing the non-instantaneous nature and the use of down/up endpoints.
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?
Single sentence, front-loaded with action and resource, no wasted words. Meets the 'every sentence earns its place' criterion.
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 4 parameters, no output schema, and existing annotations, the description adequately explains the tool's purpose. However, the queuing behavior and usage of two endpoints could be more explicitly tied to parameter usage.
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 documentation covers 100% of parameters. The description does not add additional meaning beyond what the schema provides (e.g., explaining the flags' role in the down/up process). 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 clearly states it queues a shutdown followed by startup, specifying the verb 'queue' and resource 'container restart' via Ploi endpoints. It distinguishes from sibling tools like ploi_start_container and ploi_stop_container.
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 explicit guidance on when to use this tool versus alternatives (e.g., ploi_restart_server). It implies for restarting containers but lacks context on prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reboot a Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| server_id | Yes | Ploi server ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior. Description adds no extra context about consequences (e.g., downtime, queued jobs), authentication needs, or whether restart is graceful. Fails to augment annotation data.
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?
Extremely concise and front-loaded. However, it is so minimal that it borders on under-specification; a slightly more descriptive verb (e.g., 'rebbot' is fine but could be 'gracefully restart') would improve clarity without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (single param, no output schema), the description is minimally complete. However, it omits any mention of return value or side effects beyond the destructive hint, which an agent might need for a reboot 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?
Schema coverage is 100% for the single parameter. The description ('Reboot a Ploi server') adds no additional meaning beyond the schema's 'Ploi server ID.' Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly specifies the action ('Reboot') and the resource ('a Ploi server'). It differentiates from sibling tools such as ploi_update_server and ploi_restart_container.
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 on when to use this tool versus alternatives like ploi_update_server or when not to use it (e.g., server must be running). No preconditions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queue a Docker container for startup on a Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| flags | No | Additional docker-compose flags. | |
| server_id | Yes | Ploi server ID. | |
| container_id | Yes | Ploi Docker container ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the behavioral nuance of 'Queue', implying the operation may be asynchronous—a detail beyond annotations. However, it does not disclose potential side effects or execution details.
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, concise sentence that conveys the core purpose without unnecessary words. Every part serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 3 parameters and no output schema, the description covers the basics. However, it omits clarification on the queuing mechanism, expected response, or error states.
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?
With 100% schema description coverage, the baseline is 3. The description adds no additional meaning or context to the parameters beyond what the schema already 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 clearly states the action ('Queue a Docker container for startup') and the resource ('on a Ploi server'), effectively distinguishing from stop/restart. However, it does not explicitly differentiate from the restart sibling tool.
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 versus alternatives like restart_container or start_container. The description is purely functional with no context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start installation for a custom Ploi server after the returned SSH command has been run.
| Name | Required | Description | Default |
|---|---|---|---|
| server_id | Yes | Ploi server ID. | |
| webhook_url | No | Webhook called when server installation completes. | |
| install_monitoring | No | Whether to install monitoring. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutability (readOnlyHint=false) and non-idempotency. The description adds the SSH command precondition, but does not disclose what happens on failure or if the SSH command hasn't been run. Adequate but not rich.
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 sentence that is front-loaded and contains no redundant words. 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?
The description covers the core action and precondition. However, it could be improved by noting that installation may be asynchronous or that it returns immediately, given no output schema. Still 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?
Schema coverage is 100%, so each parameter already has a description. The tool description does not add additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it starts the installation for a custom Ploi server after a prerequisite SSH command has been run. This distinguishes it from sibling tools like ploi_create_custom_server (which creates the server) and ploi_restart_server.
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 states the precondition 'after the returned SSH command has been run,' providing a clear when-to-use condition. However, it does not explicitly list alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queue a Docker container for shutdown on a Ploi server.
| Name | Required | Description | Default |
|---|---|---|---|
| flags | No | Additional docker-compose flags. | |
| server_id | Yes | Ploi server ID. | |
| container_id | Yes | Ploi Docker container ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are provided (readOnlyHint=false, destructiveHint=false) and the description adds the 'queue' aspect, indicating the shutdown is asynchronous and non-destructive. It clarifies behavior beyond annotations, though it could detail side effects like whether the container must be running.
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 of 9 words with no filler. Every word is essential, making it highly concise and structured.
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?
While the description covers the primary action, it lacks context such as whether the container must be running, what happens if already stopped, or any side effects. For a tool with no output schema and moderate complexity, more detail would improve completeness.
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 clear descriptions for all parameters. The tool description does not add significant meaning beyond the schema, but it does not contradict or confuse. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Queue...shutdown') and clearly identifies the resource (Docker container) and platform (Ploi server). It effectively distinguishes from sibling tools like ploi_start_container or ploi_delete_container.
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 does not explicitly state when to use this tool versus alternatives like ploi_restart_container or ploi_delete_container. Usage is implied but lacks guidance on prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a Docker container name or compose deploy script.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New container name. | |
| server_id | Yes | Ploi server ID. | |
| container_id | Yes | Ploi Docker container ID. | |
| deploy_script | No | Updated Docker Compose YAML. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate that this is a write operation (readOnlyHint=false) with possible side effects (openWorldHint=true) and no destruction (destructiveHint=false). The description adds that it updates name or deploy script but does not disclose authorization needs, operation idempotency, or response behavior. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence conveys the core operation without fluff. It is front-loaded with the verb and resource. Could be slightly more precise but is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details on return value (no output schema), prerequisites (e.g., server and container must exist), or side effects beyond the update. For a straightforward update tool, this is acceptable but not 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% with each parameter having a description. The description's mention of 'name or compose deploy script' roughly matches the schema's descriptions for those fields, adding no significant new meaning. Baseline is 3 due to high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Update' and the resource 'Docker container', and specifies the modifiable attributes 'name or compose deploy script'. This distinguishes it from sibling tools like create (which creates a new container) and delete (which removes a container).
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 does not explicitly state when to use this tool versus alternatives or when not to use it. While it is clear from the name and siblings that this tool is for updating an existing container, the lack of explicit guidance lowers the score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update server metadata such as name, IP address, and SSH port.
| Name | Required | Description | Default |
|---|---|---|---|
| ip | No | New server IPv4 address. | |
| name | No | New server name. | |
| ssh_port | No | SSH port for the server. | |
| server_id | Yes | Ploi server ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). Description adds no further behavioral context, but is consistent.
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?
Single sentence, 9 words, no fluff. Very concise, though could trade some conciseness for richness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description does not explain return value, side effects, or behavior when partial parameters are provided. Lacks context for a 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 description coverage is 100%, so baseline is 3. Description mentions some parameters (name, IP, SSH port) but adds no additional semantic 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?
Clearly states verb 'Update' and resource 'server metadata', listing specific fields (name, IP address, SSH port). Distinguishes from sibling tools like ploi_restart_server or ploi_update_site.
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 explicit guidance on when to use this tool versus alternatives like ploi_update_site or ploi_restart_server. Lacks prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update site properties. Domain changes are processed asynchronously by Ploi.
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes | Ploi site ID. | |
| server_id | Yes | Ploi server ID. | |
| root_domain | No | New root domain for the site. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a mutation with no destruction, and the description adds key behavioral detail: domain changes are asynchronous. This goes beyond the structured fields and helps the agent understand potential delays.
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 concise sentences with essential information. No redundancy or unnecessary words. The front-loaded purpose and async detail are well-structured.
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 update tool with 3 parameters and no output schema, the description covers the main action and async behavior. It lacks error details or prerequisites but is sufficient given the annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The tool description does not add additional meaning beyond what the schema provides. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates site properties, with a specific note about asynchronous domain changes. It distinguishes from sibling tools like create and delete but does not explicitly differentiate from other update tools (e.g., ploi_update_server).
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 on when to use this tool versus alternatives. The description lacks context for when to prefer this over create_site or deploy_site, and no when-not-to-use conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the NGINX configuration for a Ploi site. Ploi may require a reload/restart afterward.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Full NGINX configuration file contents. | |
| site_id | Yes | Ploi site ID. | |
| server_id | Yes | Ploi server ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint: false, idempotentHint: false, destructiveHint: false. The description adds that the action replaces config and may trigger a reload/restart, which is valuable context beyond annotations. However, it does not detail potential side effects or error conditions.
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 consists of two concise sentences that front-load the primary purpose and add a crucial post-action note. Every word serves a purpose, and there is no extraneous 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?
Given the moderate complexity (3 required params, no output schema), the description covers the core action and post-action requirement. However, it omits details like whether the content must be valid NGINX syntax, if existing config is overwritten completely, or error handling. It is minimally complete but has noticeable 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?
Input schema covers all three parameters with descriptions (content, site_id, server_id) at 100% coverage. The description does not add additional semantics beyond what the schema already provides, 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 clearly states 'Replace the NGINX configuration for a Ploi site,' using a specific verb ('Replace') and a specific resource ('NGINX configuration for a Ploi site'). This distinguishes it from sibling tools like ploi_get_site_nginx_configuration (read) and ploi_deploy_site (deploy 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?
The description notes that Ploi may require a reload/restart after replacement, providing some usage context. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to update config vs. deploy) or include when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0ploi_create_containerploi_create_custom_serverploi_create_serverploi_create_siteploi_delete_containerploi_delete_serverploi_delete_siteploi_deploy_siteploi_duplicate_databaseploi_forget_databaseploi_get_containerploi_get_databaseploi_get_ip_addressesploi_get_serverploi_get_server_providerploi_get_siteploi_get_site_nginx_configurationploi_list_backup_configurationsploi_list_containersploi_list_databasesploi_list_server_providersploi_list_serversploi_list_sitesploi_restart_containerploi_restart_serverploi_start_containerploi_start_custom_server_installationploi_stop_containerploi_update_containerploi_update_serverploi_update_siteploi_update_site_nginx_configurationScored across 32 tools
Each tool targets a distinct resource and action. Categories like servers, sites, databases, and containers have clear boundaries with no overlapping operations.
All tools follow a consistent 'ploi_verb_noun' pattern (e.g., ploi_list_servers, ploi_create_site), making it easy to infer function from name.
With 32 tools, the set is on the high side but still reasonable for managing multiple server aspects (servers, sites, databases, containers, providers, backups, IPs). A slight reduction could improve focus.
The tool surface covers servers, sites, and containers well, but databases lack create/delete operations and backups only list configurations. Notable gaps for a server management tool.
Deploy and manage your apps, databases, storage, and scheduled jobs from your AI agent
Deploy and manage applications, databases, domains, and git repos
Deploy full-stack apps (Postgres, Redis, S3, workers, backups) from Claude or curl. 59 MCP tools.
The bridge from K2 agents through Wrangler to your master AI - safe, approval-gated Cloudflare ops.
