Local MCP server for Cloady — gives AI assistants the whole Cloady API as tools: workspaces, apps, deploys, environment variables, domains, volumes, members, integrations, billing and support tickets.
Generated from Cloady's OpenAPI contract, so every REST operation is a tool named after its operation id (listVars, createVar, deployApp, execCommand). It runs over stdio and calls https://cloady.com with your API token.
Create an API token in the dashboard under Account → API tokens.
claude mcp add cloady -e BEARER_TOKEN_CLOADY=cldy_… -- npx -y @cloady/mcp{
"mcpServers": {
"cloady": {
"command": "npx",
"args": ["-y", "@cloady/mcp"],
"env": { "BEARER_TOKEN_CLOADY": "cldy_…" }
}
}
}API_BASE_URL overrides the target if you run Cloady elsewhere.
Related MCP server: Coolify MCP Server
One per API operation. Arguments are the operation's path parameters, query parameters and body fields flattened into one object, so createVar takes workspaceSlug, appSlug, env, region, key, value and isSecret.
The token's scope (read / deploy / full) and your workspace role are enforced by the API on every call, exactly as they are for the dashboard and the SDKs.
Full reference at cloady.com/docs.
This repository contains the source and build already published as @cloady/mcp@0.5.0 on npm, plus directory packaging. Run npm install and npm start. The Cursor plugin uses the pinned npm release. MCPB bundles include production dependencies.
This local server forwards tool arguments to the Cloady API using your configured API token. See Cloady Privacy Policy for data handling and contact information. Use the minimum necessary token scope; write tools can change or delete resources.
The 0.5.1 desktop bundle adds tool titles and conservative read/write annotations to the 0.5.0 API implementation. The Cursor configuration continues to use the published npm 0.5.0 release.
Accept a workspace invitation
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a destructive, non-read-only operation, but the description adds no behavioral context beyond restating the action. It does not disclose that accepting likely consumes the invitation, grants workspace membership, or requires authentication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence with no redundancy and front-loads the action. It is appropriately sized for the simple operation it describes.
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 mutating tool with one parameter, no output schema, and no parameter descriptions, the description is too sparse. It lacks side-effect disclosure, token source/format, and usage context, leaving an agent to guess important 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 has a single token parameter with no description (0% coverage), and the description does not explain what the token is, where it comes from, or its format. The parameter name and tool name allow some inference, but the description itself adds no semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Accept') and a clear resource ('workspace invitation'), making the tool's purpose immediately understandable. It also distinguishes itself from sibling tools like declineInvitation and getInvitation through the action verb.
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 declineInvitation or getInvitation. It does not mention prerequisites such as possessing a valid invitation token or explain the context in which accepting is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a message to a support ticket
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| requestBody | No | The JSON request body. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=true, so the agent already knows this is a mutating operation. However, the description adds no behavioral context beyond 'add', such as irreversibility, side effects, whether the ticket must exist, or what happens on failure. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no wasted words. The action and object are front-loaded, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool flagged with destructiveHint=true and no output schema, the description is too thin. It lacks usage conditions, side-effect disclosure, return expectations, and any distinction from related ticket tools, leaving the agent to infer important 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 50%: id has no description and requestBody is only described as 'The JSON request body.' The tool description implies id refers to a support ticket and body is the message text, adding some meaning, but it does not explicitly map parameters or explain the nested structure.
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 ('Add') and resource ('a message to a support ticket'), making the core action clear. It is distinguishable from siblings like createTicket, updateTicket, and streamTicketMessages, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as updateTicket or streamTicketMessages, and no exclusions or preconditions are stated. The sibling list provides context but the description itself gives no routing help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change workspace billing tier
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation indicates this is a mutating action, but the description adds no context about billing impact, reversibility, or potential side effects. It does not contradict the annotations, but it also does not meaningfully expand on them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It is concise, though arguably too terse to fully support agent decision-making.
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 important context such as return behavior, relationship to listTiers or getWorkspaceBilling, and any caveats about changing a billing tier. Given the action's destructive nature, more contextual detail is expected.
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 parameter names workspaceSlug and tier are somewhat self-explanatory, but the description does not clarify where to obtain the slug or what tier values are accepted. The schema only provides a generic description for requestBody and no domain-specific explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: changing the workspace billing tier. It is distinct from read-only tools like getWorkspaceBilling and listTiers, though it does not specify what tier values are valid.
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 related billing tools, such as listing available tiers first or checking current billing state. The description gives no prerequisites or conditions for calling it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the account's sign-in security state
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the readOnlyHint annotation and does not contradict destructiveHint. However, it adds no behavioral context beyond 'read', such as authentication requirements, rate limits, or what side effects (if any) are expected.
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 or extraneous words. It is appropriately sized for a parameterless read operation.
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 clarify what 'sign-in security state' means and what the caller can expect in the response. It does not, leaving the return value ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so no parameter documentation is needed. The description adds no parameter meaning, but the schema is trivially complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Read') and a general resource ('account's sign-in security state'), but 'security state' is vague and the tool name 'checkPassword' suggests something more specific. It does not clearly differentiate from related read operations like getNotificationPreferences or getAccountBilling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives such as updatePassword, setMfa, or verifyPhone. The description only states that it reads security state, leaving the agent to infer applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the slug that would actually be used; suffixed is true when the requested one was taken and a numeric suffix was added.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds behavioral context about the suffix logic (the requested slug may be taken and a numeric suffix added), which is not evident from annotations. It discloses the conditional return behavior clearly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core purpose and key behavioral detail (suffix condition) without any filler. It is appropriately concise for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only check with one parameter, the description covers the essential behavior. However, it does not explicitly state the return structure (e.g., an object with 'slug' and 'suffixed' fields), though it implies it. Given the lack of an output schema, a slight gap exists, but the core functionality is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines 'slug' as a string, with 0% description coverage. The description clarifies the parameter's role as the 'requested' slug, explaining that the tool checks if it's taken and may add a suffix. This adds meaningful 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's function: returns the slug that would actually be used, and explains the suffixed flag condition. It uses a specific verb (returns) and resource (slug), and distinguishes it from workspace creation/management tools by focusing on the check behavior.
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 provide any guidance on when to use this tool versus alternatives. It doesn't mention that it should be used before creating a workspace or that createWorkspace is the actual creation step. The intended use case is implied by the name and behavior, but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a new deployment for an app
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate destructiveHint=true and readOnlyHint=false, which already communicate that this is a mutating action. The description does not add further context about potential side effects, such as triggering a new deployment version or affecting current app state, but it does not contradict the annotations either.
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, clear sentence with no fluff. It is concise and well-structured, delivering the essential purpose without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema or description of the response format, success/failure behavior, or side effects. The tool involves nested objects and multiple parameters, yet the description provides minimal context beyond the basic action, making it incomplete for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only the requestBody parameter has a description ('The JSON request body.'), and it is generic. workspaceSlug, appSlug, env, and region lack any explanation, leaving the agent to guess their meanings and allowed values despite the env enum. Schema coverage is only 20%, and the description does not compensate.
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 'Trigger a new deployment for an app' clearly states the action (trigger) and resource (deployment for an app), distinguishing it from related tools like deployApp and redeployApp. It lacks some specificity about the deployment context, but the core purpose is 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?
The description provides no guidance on when to use this tool versus alternatives like deployApp, redeployApp, or rollbackDeploy. No conditions or prerequisites are mentioned, leaving the agent to infer the appropriate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new domain for an app
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Create a new domain', which is a non-destructive action, but the annotations declare destructiveHint: true. This is a direct contradiction and could mislead about whether the operation may destroy existing data or configuration.
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 unnecessary words. However, it is so brief that it sacrifices useful context that could clarify parameter roles or side effects.
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 omits critical context such as the need for a request body, the meaning of isPrimary, potential side effects, or what happens after creation. It is insufficient for a tool with a nested requestBody object and five parameters.
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 description provides no explanation of the parameters beyond the schema itself. Fields like workspaceSlug, appSlug, env, region, isPrimary, and redirectTo are left entirely unexplained, and the schema description coverage is only 20%, so the description adds little to parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'domain for an app', making the tool's purpose immediately obvious. It distinguishes this tool from siblings like deleteDomain and updateDomain by specifying the creation 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 that this tool should be used when creating a new domain, but it does not explicitly explain when to prefer it over related domain tools or provide any context about prerequisites. The guidance is inferred from the name and verb rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The credentials are derived and expire on their own; access: "write" needs the developer role. Buckets are named <instance id without dashes>-<volume>.
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions that credentials are derived and expire, and the bucket naming convention, but does not disclose the full behavior (e.g., that it returns temporary credentials, creates a session, or has side effects). The destructiveHint annotation is not addressed at all, so the description fails to clarify the operation's safety profile.
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, which is concise, but it is dense and cryptic. It packs multiple technical details without clear separation or prioritization, making it less readable than ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides some contextual details about credentials and buckets, but it does not give enough information for an agent to understand what the tool actually does, what it returns, or when to use it. It relies heavily on the tool name for context, which is insufficient for complete 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?
The description explains the 'access' parameter by noting that 'write' access requires the developer role, which adds meaning. However, it does not explain 'workspaceSlug' or how the bucket naming relates to the parameters, leaving some parameters under-specified.
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 lacks an explicit verb like 'creates' or 'generates', instead stating technical facts about credential expiry and bucket naming. The tool name and title imply the purpose, but the description itself does not clearly state that it creates an S3 session.
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?
There is no guidance on when to use this tool versus alternatives (e.g., endS3Session). The description does not mention prerequisites, typical scenarios, or distinguish this from related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a short-lived SSH session credential for a running container
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the trait 'short-lived' but does not explain side effects, authentication requirements, or potential failures. Annotations already indicate it is non-read-only and destructive, but the description offers no additional context beyond that.
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 clear sentence with no unnecessary fluff. It is appropriately concise and front-loaded with the core 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?
The tool is missing essential contextual information: no output schema, no description of return values, no parameter explanations beyond one generic field, and no guidance on expected behavior or failure modes. Given the complexity of the input schema and the range of sibling tools, the description is significantly under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only the requestBody parameter has a description, which is generic ('The JSON request body') and does not explain its nested component field. The other four parameters (env, region, appSlug, workspaceSlug) are completely undocumented, leaving the schema largely unexplained.
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: creating a short-lived SSH session credential for a running container. It uses a specific verb and resource, and it is distinct from sibling tools like createS3Session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as needing a running container, nor does it differentiate from execCommand or other remote-access tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new support ticket
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate this is a mutating operation (readOnlyHint=false, destructiveHint=true), and the description adds no behavioral context beyond what the name implies. No side effects, prerequisites, or response behavior 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 concise sentence with no wasted words. It is front-loaded and appropriately minimal for a simple create operation, though it sacrifices explanatory value for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so an agent does not know what the tool returns, and no guidance is given about authentication, side effects, or how this differs from ticket-related siblings. The schema covers parameters, but operational context 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%, so the schema fully documents the requestBody and its required subject/body fields. The description adds no parameter detail, but the schema already carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create') and a clear resource ('support ticket'), so an agent can tell this tool creates a ticket rather than listing, updating, or messaging one. It does not explicitly distinguish it from addTicketMessage, but the primary intent is 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 guidance is provided about when to use this tool versus sibling tools like listTickets, updateTicket, or addTicketMessage. The name implies creating a new ticket, but there is no explicit context or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new API token for the current user
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose any side effects, such as the token being displayed only once or potential security implications. The annotations indicate destructiveHint=true, but the description provides no elaboration on what that means for the caller.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and to the point, with no unnecessary words. It effectively communicates 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 description is minimal, missing mention of potential returned data or any important caveats like token visibility. However, since there is no output schema, the absence of return value description is not a major issue.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, requestBody, has the generic description 'The JSON request body.' but the nested fields (name, scope, expires) lack descriptions. This leaves the meaning of scope and expires unclear, especially with enum values.
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 (API token) and specifies the scope (current user). It differentiates from sibling tools like revokeToken and listTokens.
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 instead of listTokens or revokeToken. The description lacks any mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new environment variable or credential
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, indicating a mutating operation with potential side effects. The description adds no extra behavioral context, such as overwriting behavior, permission requirements, or impact on existing variables, so it fails to add value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundancy, but it is under-specified. It is not verbose, yet it also does not provide enough substance to be considered well-structured for the tool's complexity. It earns a middle score for being appropriately short but lacking informational depth.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, a nested requestBody, no output schema, and low schema coverage, the description is very incomplete. It does not mention required fields, the requestBody structure, possible values for env, or any operational side effects, leaving the agent with insufficient context to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at only 20% (only the requestBody field has a description), the description does not compensate for the undocumented parameters. It does not explain env, region, appSlug, or workspaceSlug, nor does it elaborate on the requestBody structure beyond what the schema provides. The description adds zero parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (create) and resource (environment variable or credential), which distinguishes it from sibling tools like updateVar, deleteVar, and listVars. However, it does not mention the workspace/app scope or differentiate from similar creation tools like createToken, so it is clear but not fully differentiated.
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 importVars for bulk creation or updateVar for modifying existing variables. It simply states the action without any contextual use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a workspace (requires full scope)
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, which is unusual for a creation operation and is not explained. The description only mentions the scope requirement, omitting any details about side effects, return values, or consequences. The lack of behavioral disclosure is a significant gap, and the destructive annotation appears contradictory to the 'create' semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is highly concise, though the brevity borders on under-specification. For the dimension of conciseness, it earns high marks, but the lack of content is penalized in other dimensions.
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 (nested object with multiple required fields, no output schema, and annotations that are not fully explanatory), the description is grossly incomplete. It omits expected behavior, parameter semantics, and any guidance on response or errors. The sole mention of scope requirement is insufficient for safe 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?
The only parameter, requestBody, has a description of 'The JSON request body.' which adds no meaning beyond the schema. The nested fields (name, slug, hues, tier, etc.) lack semantic explanations; the description does not clarify what these fields represent or how they should be filled. Schema coverage is technically 100% but the description is tautological.
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 and resource: 'Create a workspace'. It distinguishes from siblings like updateWorkspace and deleteWorkspace by the action, though it does not explicitly contrast them. The scope requirement is an extra but not a differentiator. Overall, the purpose is 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?
The description provides only the prerequisite 'requires full scope' but gives no guidance on when to use this tool versus alternatives like updateWorkspace. There is no mention of exclusions, preconditions beyond scope, or typical use cases. The agent must infer that creation is for new workspaces from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send workspace invitation
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructiveHint=true and openWorldHint=true, so the agent knows this is not a read-only operation. However, the description itself adds no behavioral context beyond 'send', such as what consequences sending an invitation has, whether it is reversible, or what side effects occur. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and front-loaded, with no wasted words. While it is arguably too terse to be fully useful, as a concise statement of the core action it is well-structured and immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a nested request body, a required email, an optional role enum, and no output schema, this description is incomplete. It does not mention required fields, role semantics, what happens after sending, or any distinction from related invitation tools, leaving the agent to infer critical 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 description coverage is only 50%, and the only property description, 'The JSON request body', is generic and unhelpful. The tool description does not explain workspaceSlug, email, role, or how they relate, so it adds no meaning beyond the raw schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Send') and resource ('workspace invitation'), making the tool's function clear and distinguishing it from workspace-creation and invitation-management siblings like createWorkspace, revokeWorkspaceInvitation, and acceptInvitation. It is not a tautology and adds a slight action-oriented nuance beyond the tool name.
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?
There is no guidance about when to use this tool versus alternatives such as revokeWorkspaceInvitation, listWorkspaceInvitations, acceptInvitation, or declineInvitation. The usage is only implied by the tool name and one-line description, with no mention of prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decline a workspace invitation
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false and destructiveHint=true, which the description aligns with ('decline' implies rejection/destruction). However, the description adds no extra behavioral context such as irreversibility, side effects, or authorization requirements beyond what annotations already 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 with no wasted words, and the core purpose is front-loaded. It lacks additional structure like examples or clarifications, but for its brevity it is 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 tool with one parameter, no output schema, and simple semantics, the description is minimally adequate but incomplete. It does not explain what happens on success, how the token is used, or any caveats, relying heavily on the parameter name and 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 description coverage is 0% for the single 'token' parameter. The description does not explain what the token represents, how it should be obtained, or its role in declining the invitation, placing the full burden on the schema which provides only the name and type.
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 'Decline a workspace invitation' uses a specific verb (decline) and clear resource (workspace invitation). It implicitly distinguishes from sibling tools like acceptInvitation and getInvitation by the contrasting verb, 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 guidance is provided on when to use this tool versus acceptInvitation or getInvitation. There is no mention of prerequisites, context, or exclusion criteria, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an app and purge its data
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the agent knows it's destructive. The description adds 'purge its data' which reinforces the irreversible nature. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence that is front-loaded with the main action and adds a critical detail about data purging. No 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 destructive operation with four parameters and no output schema, the description is too minimal. It doesn't explain the purpose of parameters, potential side effects on associated resources (domains, volumes), or any prerequisites. Annotations cover destructive nature, but more context is needed.
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 0%, so the description must compensate by explaining parameters, but it does not mention any of the four parameters. The parameter names are somewhat self-explanatory, but the description adds no value beyond the schema's existence.
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) and resource (app), and adds 'purge its data' which distinguishes it from other app-related tools like updateApp or deployApp. It is 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?
The description does not provide explicit guidance on when to use this tool versus alternatives. It is implied that it's for deleting an app, but no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a domain from an app
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| domainId | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already signal destructive behavior (destructiveHint: true), and the description adds no behavioral detail beyond that, such as whether deletion is permanent, cascades to DNS records, or requires the domain to be unused. There is no contradiction, but the description does not enrich the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is concise, though the brevity contributes to the lack of behavioral and parameter detail scored elsewhere.
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 tool with five parameters, three required, and no output schema, a six-word description is insufficient for an agent to confidently call it. It omits parameter semantics, return behavior, and any caveats about the deletion.
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 0% schema description coverage, the description needed to explain the parameters but only maps 'domain' to domainId and 'app' to appSlug. The required workspaceSlug and optional env/region remain undocumented and unexplained.
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 ('Delete') and resource ('domain from an app'), which clearly identifies the operation and distinguishes it from sibling tools like createDomain, updateDomain, and listAppDomains. It is not a tautology because it adds the app-scoping context.
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 createDomain, updateDomain, or listAppDomains, and no conditions or exclusions. An agent must infer the appropriate context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an environment variable or credential
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| varId | Yes | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the destructiveHint annotation and makes the delete operation explicit. It does not detail irreversibility or side effects beyond the annotation, but the annotation already covers destructive behavior, so the description adds sufficient clarity.
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 clear sentence with no unnecessary words. It is direct and easy to parse, making the tool's purpose immediately understandable.
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 low complexity and the presence of sibling tools, the one-sentence description is reasonably complete. It identifies the resource type and action, though it does not mention return behavior or error cases, which are not critical for this simple delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lists parameters like workspaceSlug, appSlug, varId, env, and region, but the description provides no explanation of these fields or how they should be used. The names are partially self-explanatory, but the description does not compensate for the lack of parameter-level documentation.
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') and the target resource ('an environment variable or credential'). This distinguishes it from sibling tools like listVars, createVar, updateVar, and revealVar by the verb and intent.
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 tool is used when an environment variable or credential should be removed, but it does not explicitly state when to prefer this over other var-related tools or mention any preconditions. The sibling list provides context, but the description itself offers no direct usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a workspace (requires full scope)
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark this as destructive (destructiveHint: true) and not read-only, so the bar for extra context is lower. The description adds the scope requirement but does not mention irreversibility, cascading deletions, or side effects, which would have been beneficial.
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 action and resource. It contains no filler or unnecessary detail, making it optimally 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 delete operation with a single slug input and no output schema, the description is minimally adequate. However, it lacks context about what happens on success or failure, or whether deletion is permanent, relying on the destructive annotation to imply consequences.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for 'workspaceSlug', and the tool description does not explain what this parameter represents or how it should be formatted. With 0% schema description coverage, the description fails to compensate, leaving the parameter meaning entirely implicit.
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') and the resource ('workspace'), and it distinguishes this tool from siblings like updateWorkspace or createWorkspace. The phrase 'requires full scope' adds a specific precondition that helps identify when this tool is appropriate.
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 mentions a scope requirement but does not explicitly state when to use this tool versus alternatives or when to avoid it. It is implied by the purpose, but there is no direct guidance on selection among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deploy an app from a git repository or upload
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, covering the mutating nature. The description adds no further behavioral context, such as whether it triggers a build, overwrites existing deployments, or has specific permission requirements. With annotations present, a 3 is appropriate because it adds minimal value beyond the annotation.
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, efficient sentence that conveys the core purpose without filler. It is front-loaded with the action and resource, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a highly nested schema, no output schema, and destructive annotations, the description is extremely sparse. It omits essential details about source types (git vs upload vs catalog), required fields, return values, and potential side effects, making it insufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, and the description provides no explanation of any parameters. The schema has a complex structure with nested objects and oneOf source types, but the tool description adds no meaning to these fields, failing to compensate for the schema's low 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 'Deploy' and resource 'app', and identifies two sources (git repository or upload). However, it does not explicitly differentiate from sibling tools like createAppDeploy or redeployApp, leaving some ambiguity about the exact scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as createAppDeploy, redeployApp, or updateApp. No conditions, exclusions, or preferred contexts are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Disconnect GitHub integration from workspace
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and readOnlyHint=false, so the description adds no new behavioral context. It does not disclose side effects, irreversibility, or external impacts (e.g., invalidating deployments) beyond the bare word 'disconnect'.
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 clear sentence with no wasted words. It is front-loaded with the action and scope, making it easy to parse.
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, the description is too sparse. It does not mention reversibility, consequences, or any required permissions. The single parameter is undocumented, and there is no output schema, leaving the agent without essential 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 description coverage is 0%, so the description must compensate. It does not explain what workspaceSlug is, how to obtain it, or its format. The parameter name is self-explanatory, but the description adds no additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (disconnect) and the target (GitHub integration) with workspace scope. It is distinct from sibling tools like linkGithubIntegration and listGithubRepos, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any conditions, prerequisites, or exclusions. An agent must infer its use from the action alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
End the caller's S3 session
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint:true and readOnlyHint:false, so the description's 'End' confirms mutation. However, it adds no additional behavioral context—no mention of side effects, reversibility, or what happens to the session. With annotations present, the description adds minimal 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?
The description is extremely short, which is concise, but it is under-specified rather than efficiently written. It front-loads the action but omits any supporting details, making it less useful than a more structured description of similar length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive action with one parameter and no output schema, the description is nearly empty. It does not explain what workspaceSlug refers to, what side effects occur, or what the tool returns. The agent has almost no information beyond the tool name and 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?
The schema has one required parameter, workspaceSlug, with 0% description coverage. The description does not mention or explain this parameter at all, leaving the agent without any semantic guidance beyond the schema's bare type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('End') and resource ('S3 session'), and the name and sibling list make it clear it's the counterpart to createS3Session. It is unambiguous about its function, though it does not explicitly differentiate itself from 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?
No guidance is provided on when to use this tool versus alternatives. It does not mention when it should be called, prerequisites, or that it should be used to terminate a session started by createS3Session. The agent must infer usage from the name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a one-off shell command in a running container (kubernetes exec)
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, covering the mutation risk. The description adds that it is a 'one-off' command (not a persistent session), which is useful context. It does not elaborate on side effects, authentication, or failure behavior, but annotations carry the safety burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no waste. It immediately conveys the action and scope, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a nested requestBody, five parameters, and no output schema, the description is grossly incomplete. It does not explain the required fields (component and command), the meaning of env or region, or how the command is executed. An agent would need to inspect the schema or make assumptions, risking incorrect invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only requestBody has a description). The description does not explain any of the five parameters (env, region, appSlug, workspaceSlug, or the nested requestBody fields). It fails to compensate for the low coverage, leaving the agent to guess parameter meanings.
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 'Run', the resource 'shell command', and the context 'in a running container (kubernetes exec)'. It is specific and distinguishes itself from sibling tools that handle deployments, logs, or git operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for one-off shell commands in containers, which is a clear usage context. However, it does not explicitly mention when to use alternatives or exclude other tools, though the unique phrasing 'kubernetes exec' sets it apart sufficiently.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get account billing information including payment methods and invoices
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds content scope but no behavioral details such as pagination, response shape, or authentication requirements; for a no-arg read-only tool this is acceptable but adds little beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the verb and object front-loaded, and it contains no filler or repetition. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only tool, the description plus annotations are sufficient to invoke it correctly. No input is needed, and the returned content is summarized well enough for selection purposes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description carries no parameter-documentation burden; the baseline of 4 applies. There are no parameter semantics to clarify.
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 ('Get') and a clear resource ('account billing information'), and it names the content scope ('payment methods and invoices'). The 'account' qualifier separates it from the sibling getWorkspaceBilling, so an agent can identify this as the account-level counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit when/when-not guidance or named alternatives. Usage is only implied by the tool name and the 'account' scope; an agent facing getWorkspaceBilling or getUserBillingState gets no routing help from this text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all services in an app instance
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'List' is consistent. However, the description adds no extra behavioral context such as pagination, filtering, or authentication requirements. Since annotations cover the safety profile, a neutral score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. It is appropriately sized for the action, though its brevity contributes to a lack of detail in other dimensions.
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 and 0% parameter description coverage, the description does not explain what services are returned, how env/region affect results, or the response format. It is minimally functional but incomplete for a tool with four parameters.
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 0%, so the description must compensate by explaining parameters. It does not mention any of the four parameters (env, region, appSlug, workspaceSlug) or their meaning, leaving the agent to guess from names alone, which is insufficient.
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 (List) and the resource (services) with a scope (app instance). It is distinct from sibling list tools like listVolumes or listAppDomains, though it doesn't explicitly name them. The purpose is 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?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. An agent must rely on the tool name alone to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read from the running pod's resolved environment at call time, so the container is the source of truth rather than the template. component is a compose service running a database.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| component | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses that the operation reads from the actual running environment at call time, implying real-time state and no mutation. This additional behavioral detail (resolved env vs. template) gives the agent a more accurate mental model of the tool's effects and data source.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two terse sentences with no redundant words. It delivers the core purpose and a key nuance in a compact, well-structured manner, making it easy to read and parse.
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 (5 parameters, no output schema), the description conveys the core purpose and emphasizes the live-environment source, but lacks details about the return value's structure (e.g., which credential fields are included) and does not explain the remaining parameters. However, the purpose is clear enough for a simple read operation, so it is mostly 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 description only explains the `component` parameter (a compose service running a database). The other four parameters (`workspaceSlug`, `appSlug`, `env`, `region`) are left entirely undocumented, and the schema provides no descriptions either. With zero schema coverage, the description must compensate for all parameters, which it does not.
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 that the tool reads from the running pod's resolved environment at call time to obtain database credentials, and it explicitly notes that the container is the source of truth rather than the template. This makes the tool's purpose unambiguous and distinct from actions that might operate on config or template state.
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 a clear semantic contrast—'source of truth rather than the template'—which implicitly tells the agent when to use this tool (when live environment credentials are needed, not the template-defined ones). It does not explicitly state alternative tools to use in other scenarios, but the guidance is sufficient for a basic call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a database component's schemas and tables
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| schema | No | ||
| appSlug | Yes | ||
| component | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint: true and destructiveHint: false, which align with the non-destructive 'list' operation. The description itself is consistent with these annotations and does not add misleading context. It could mention that no modifications occur, but the annotations already cover this.
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 directly conveys the tool's purpose. There is no redundant or extraneous information, making it easy for an agent to quickly grasp the function.
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 listing operation, the description is adequate. It does not mention output format or pagination, but the absence of an output schema reduces the need for such details. However, it could clarify whether the 'schema' parameter acts as a filter, which 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?
The schema defines six parameters without any descriptions, and the description does not explain their meaning or usage. While names like workspaceSlug and appSlug are somewhat self-explanatory, parameters such as 'schema' and 'component' are ambiguous in context. Since schema description coverage is 0%, the description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: listing a database component's schemas and tables. It uses the specific verb 'list' and identifies the resource (database component). This distinguishes it from sibling tools like runDbQuery or getDbCredentials.
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 mention when to use this tool versus alternatives such as runDbQuery or getDbCredentials. However, the read-only listing nature is implied by the verb 'list', but no direct comparison or conditional guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
With no sha, diffs the working tree. path narrows it to one file. Large patches come back with truncated: true.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| sha | No | ||
| path | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive, and the description adds that without a `sha` it diffs the working tree and that large patches are truncated with `truncated: true`. This provides useful behavioral context beyond the annotations. It doesn't contradict any 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?
Two sentences with no filler, front-loading the core behavior and then adding the truncation note. It's appropriately sized and 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?
With six parameters and no output schema, the description should explain the return format, parameter roles, and any other behaviors. It only covers the diff behavior and truncation, leaving much unstated. This is incomplete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the `sha` and `path` parameters, but the schema has 0% coverage, so it carries the burden of explaining all six parameters. It leaves `env`, `region`, `appSlug`, and `workspaceSlug` unexplained. This is insufficient for an agent to correctly use the tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it diffs the working tree and can narrow to a file with `path`. It specifies a verb and resource, making the purpose clear. However, it doesn't explicitly differentiate from sibling tools like runGitAction or inspectSource, so it's not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives like runGitAction or inspectSource. It only implies usage by describing the diff operation. There are no exclusions or conditions that would help an agent choose this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the repository inside the running container by pod exec, so it is ground truth rather than the deploy record. Returns {ok:false, reason} when the app has no repo, no pod, or no git.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| limit | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the behavioral detail that it uses pod exec and returns a specific failure format, which provides value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words. The key method (pod exec) and distinguishing factor (ground truth) are front-loaded, making it efficient and easy to parse.
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 explains failure conditions but omits the success response format and provides no parameter guidance. For a tool with 5 parameters and no output schema, this is incomplete; an agent would struggle to construct a correct call, especially for env, limit, and region.
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 description provides no parameter semantics. With schema description coverage at 0%, the description fails to compensate for the undocumented parameters (env, limit, region). An agent has no guidance on how to fill these fields beyond their names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('reads'), a specific resource ('repository'), and the method ('pod exec'), and explicitly distinguishes it from the deploy record. This makes the tool's purpose clear and distinct from sibling tools like getGitDiff or listBranches.
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 primary use case (ground truth over deploy record) and specifies failure conditions, which helps an agent decide when to call it. However, it does not explicitly name alternative tools or state when not to use it, so the guidance is inferred rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get invitation details by token
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds token-based lookup behavior but does not clarify what happens for invalid, expired, or already-accepted invitations, and it does not leverage openWorldHint to warn that invitation state may change externally. With annotations covering the main concerns, this is 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 a single compact sentence with no filler and the key action is front-loaded. It is concise to a fault, but every word earns its place; additional contextual detail could be added without harming clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only lookup with annotations covering safety, the description is close to sufficient, but it omits what 'details' are returned and does not distinguish invitation tokens from other token types. Since there is no output schema, a bit more return-value context would help an agent know what to expect.
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 0%, and the only parameter, 'token', has no description in the schema. The description repeats that the lookup is 'by token' but does not explain what kind of token is expected, its format, or how it differs from other token types in the API.
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 names a specific verb and resource ('Get invitation details') and identifies the lookup key ('by token'). It is clearly a read operation and is distinguishable from sibling actions like acceptInvitation, declineInvitation, and revokeWorkspaceInvitation, though it does not explicitly contrast itself with listWorkspaceInvitations.
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 instead of listWorkspaceInvitations, acceptInvitation, or declineInvitation. The description does not state whether this is a prerequisite step before accepting/declining an invitation or how it relates to workspace-level invitation listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the authenticated user
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not repeat safety. It adds minimal behavioral context by specifying 'authenticated user', but does not elaborate on the response shape or any potential errors. Given the annotations, a 3 is appropriate—it adds some context but not rich behavioral detail.
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 wasted words. It is front-loaded with the core action and resource, making it immediately actionable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with no parameters and no output schema, the description is sufficient for an agent to know it returns the authenticated user. While it doesn't detail the response structure, the simplicity of the operation makes this acceptable, and no critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema covers everything. With no parameters to explain, the description adds nothing beyond the schema, but per the rubric, a baseline of 4 applies when there are no parameters. The description is adequate.
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 'get' and the resource 'the authenticated user', which is specific and unambiguous. It distinguishes this tool from siblings like listTokens, getUserBillingState, and listWorkspaces, making it obvious that it retrieves the current user's profile.
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 retrieving the authenticated user but does not explicitly mention when to use it over alternatives or any exclusions. Since it's a self-explanatory getter, the usage is implied rather than explicit, warranting a score of 3.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get notification preferences for the current user
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description correctly aligns with them. The description adds the scoping detail 'for the current user', which is useful, but does not describe return format or any other behavioral characteristics. It adds some value beyond annotations but not extensive.
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. There is no unnecessary information or repetition.
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 is sufficient for a simple getter with no parameters and annotations covering the safety profile. However, the lack of an output schema means the agent does not know the structure of the returned notification preferences, which could be a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the schema provides no parameter information, so the description does not need to compensate. The baseline of 4 is appropriate; the description does not add parameter details, but none are needed.
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 a specific verb ('get'), resource ('notification preferences'), and scope ('current user'), making it distinct from the sibling updateNotificationPreferences. It is unambiguous and actionable.
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 explicit guidance on when to use this tool versus the sibling updateNotificationPreferences. However, the verb 'get' implies a read operation, and the tool name itself suggests the usage context, but there is no explicit statement about alternatives or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get public pricing information for all tiers
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral details beyond restating the purpose; it does not disclose quirks like empty results or error handling, but for a public info tool this is acceptable.
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 waste. It is front-loaded with the core action and resource, making it immediately clear to an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema, annotations cover safety), the description is sufficient. It clearly states what the tool returns without needing to elaborate on return format, which is acceptable for a public info getter.
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 zero parameters, so the schema coverage is trivially 100%. The description does not need to explain parameters, and the baseline for zero-parameter tools is 4. The description adds no parameter-related information because none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('public pricing information') with a clear scope ('for all tiers'). It is unambiguous and distinct from sibling tools like listTiers, which likely focus on tier features rather than pricing.
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 public pricing is needed, but it does not explicitly contrast with alternatives or provide when-not-to-use guidance. For a simple read-only getter, this is adequate but leaves the agent to infer when to choose it over similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single support ticket with all messages
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the behavioral detail that the response includes 'all messages', which goes beyond the bare 'get ticket' statement. However, it does not describe the response format or any potential pagination or ordering of messages, so it adds limited behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and key detail ('with all messages'). There is no redundant phrasing or unnecessary words, making it perfectly concise and 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 read operation with one parameter and no output schema, the description covers the essential purpose and the key output characteristic (all messages). While it does not detail the exact return fields, the tool's simplicity and the sibling tool context (listTickets, streamTicketMessages) make it adequately complete. A dedicated output schema or a brief note on response structure would make it a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'id' with no description (0% coverage). The description does not explicitly define 'id' as the ticket identifier, but the tool name and description 'Get a single support ticket' make it strongly implied. This partial compensation for the missing schema description warrants a 3, but a more explicit statement of the parameter's role would push it higher.
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 'Get' and the resource 'single support ticket', and explicitly notes it includes 'all messages'. This distinguishes it from listTickets (which lists multiple) and streamTicketMessages (which streams messages), making its purpose unambiguous even without inspecting the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving a specific ticket when you have its ID, which is a clear usage context. However, it does not explicitly mention alternatives like listTickets for discovery or streamTicketMessages for real-time updates, so it lacks explicit exclusion guidance. This is a minor gap, giving a 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get user billing state (free availability and payment method status)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and destructiveHint annotations already cover the primary behavioral aspect (safe, read-only operation). The description adds little beyond that, only hinting at the type of data returned without discussing side effects, errors, or data freshness, so it meets but does not exceed the baseline set by the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that conveys the purpose and scope without redundancy. It is appropriately brief for a parameterless getter, and the parenthetical provides useful detail without fluff.
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 no output schema is provided, the description serves as the primary source for understanding what the tool returns. It mentions key aspects (free availability, payment method status) but does not elaborate on possible values or formatting. This is slightly incomplete but sufficient for a simple query, especially with the sibling context clarifying the scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, and the schema accurately reflects that with 100% coverage. There is nothing ambiguous or undocumented, so the description needs no additional parameter explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the user billing state, and the parenthetical ('free availability and payment method status') specifies exactly what information is included. This distinguishes it from similar tools like getAccountBilling and getWorkspaceBilling by focusing on the user level.
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 indicate when to use this tool versus the closely related getAccountBilling or getWorkspaceBilling tools. It also mentions no preconditions or timing considerations, leaving the agent without guidance on tool selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Credentials are derived, not stored, so they are stable for the volume and need no rotation step. volume is a name from listVolumes.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| volume | Yes | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses meaningful behavior beyond annotations: credentials are derived, not stored, stable for the volume, and require no rotation. This complements the readOnlyHint and adds context an agent would not get from the schema or annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler, front-loading the most important behavioral fact and ending with a precise parameter reference. Every sentence 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 credential stability and the source of `volume`, but with no output schema it does not state what the returned keys look like. It also leaves env and region semantics to inference, though the simple read-only nature of the tool reduces the impact of these gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only explains `volume` as a name from listVolumes; workspaceSlug, appSlug, env, and region receive no additional meaning despite being undocumented in 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 title and description together make it clear the tool returns volume credentials, and the description adds that they are derived rather than stored. However, the description never explicitly states the action ('get volume keys') or return value, and it does not differentiate this tool from siblings like getDbCredentials.
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 tool is for retrieving stable volume credentials and instructs that `volume` must come from listVolumes, which is a useful workflow hint. It does not name alternatives or state when not to use the tool, so usage guidance is mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a workspace by slug
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose any behavioral traits beyond the obvious 'get' action. While annotations confirm read-only and non-destructive behavior, the description itself adds no additional context about side effects, errors, or permissions.
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 unnecessary words or repetition. It efficiently conveys the essential purpose in a minimal, well-structured format.
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 simplicity of the tool (single parameter, read-only), the description covers the basic purpose, but it omits any mention of the return value or potential error cases. Since there is no output schema, a brief note about expected output 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?
The description clarifies that the workspace is identified 'by slug', directly explaining the meaning of the 'workspaceSlug' parameter. This adds value beyond the schema, which only lists the parameter name and type without any description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'workspace by slug', making it distinct from sibling tools like listWorkspaces or checkWorkspaceSlug. It specifies the scope of retrieval by slug, leaving no ambiguity about what the tool does.
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 listWorkspaces (for multiple workspaces) or checkWorkspaceSlug (for availability checking). It is left to the agent to infer usage context from the parameter and sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get workspace billing info
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, which cover the main behavioral aspects. The description adds nothing beyond 'get info', which aligns with the read-only nature. Since the annotations carry the burden, a score of 3 is appropriate.
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 unnecessary words. It is front-loaded with the verb 'Get' and immediately states the resource, making it highly efficient and 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 getter with no output schema, the description is minimally sufficient, but it lacks essential context such as usage guidance vs. account billing or any detail about what 'billing info' includes. It is not completely self-contained for an agent to decide when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines workspaceSlug as a string without further description. The description does not mention or clarify this parameter. Although the name is self-explanatory, the low schema coverage (0%) means the description should compensate, but it does not.
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 'Get' and the resource 'workspace billing info', which is specific. It does not explicitly differentiate from sibling tools like getAccountBilling or getUserBillingState, but the tool name itself indicates the workspace scope, so it is clear enough.
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 getAccountBilling or changeBillingPlan. There is no mention of context, prerequisites, or when not to use it, leaving the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk-create environment variables, skipping keys already set
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readonly, open-world, and destructive hints. The description adds the specific behavior 'skipping keys already set' which is not covered by annotations, providing useful transparency about idempotency and non-overwrite semantics.
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 fluff. It immediately conveys the core purpose and a key behavioral nuance, fitting within the ideal length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has nested objects and no output schema, the description provides only minimal context. It lacks details on response format, error handling, partial failure behavior, or parameter relationships, so an agent may need to infer from the schema or sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only requestBody has a generic description). The description does not compensate for the lack of explanations for env, region, appSlug, or the entries array structure, leaving significant ambiguity for an agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Bulk-create environment variables' clearly distinguishes it from the single-item createVar tool and other variable-related operations. It also notes the 'skipping keys already set' behavior, which is a distinctive feature.
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 it (when needing to create multiple variables at once) and the skip-existing behavior guides selection over createVar. However, it does not explicitly name alternative tools or state when not to use it, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect a source and preview its template
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description uses 'Inspect' and 'preview,' which imply read-only behavior, but the annotations indicate destructiveHint=true and readOnlyHint=false. This is a direct contradiction, making the tool's behavior unclear and potentially misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is minimal but not concise in an effective way. It omits crucial details about parameters, behavior, and side effects, making it under-specified rather than appropriately sized.
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 and no parameter explanations, the description lacks essential context. It does not mention the tool's purpose beyond a vague inspection, nor does it address potential destructive actions indicated by 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?
The description provides no explanation of the two parameters (workspaceSlug and requestBody) or the nested 'source' object with its oneOf variants. It fails to clarify the meaning of fields like repoUrl, uploadId, or catalog name, leaving users to guess the required inputs.
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 'Inspect a source and preview its template' is vague. 'Source' could refer to a git repository, upload, or catalog, and 'template' is undefined. It lacks a clear resource and specific verb that distinguishes it from sibling tools like listTemplates or getWorkspace.
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?
There is no guidance on when to use this tool versus alternatives. The description does not mention any conditions, prerequisites, or comparisons to sibling tools such as listTemplates or deployApp.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Link GitHub installation to workspace
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation is known, but the description adds no behavioral context beyond that. It does not mention side effects, idempotency, prerequisites, or whether an existing integration is replaced.
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 clear sentence with no wasted words, but it essentially restates the tool name and carries no additional structural information. It is concise but under-specified.
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, open-world mutation with a nested request body and no output schema, this description is too thin. It lacks prerequisites, side effects, and any guidance on how the GitHub installation link behaves within a workspace.
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 50% and the only parameter description is the generic 'The JSON request body.' The description adds only a loose semantic mapping (installation → workspace) and does not explain installationId or workspaceSlug meaning, formats, or relationships.
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 names a specific verb ('Link'), a resource ('GitHub installation'), and a target ('workspace'). This distinguishes it from sibling tools like disconnectGithubIntegration and listGithubRepos, though it does not explicitly call out any alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as listWorkspaceIntegrations or disconnectGithubIntegration. The intended use case is only implied by the verb 'Link', with no exclusions or contextual conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all domains for an app in a workspace
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description's 'list' wording is consistent with the readOnlyHint annotation. However, it adds no extra transparency about pagination, output limits, or potential errors beyond what the annotations already convey.
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 efficiently conveys the purpose without unnecessary verbiage.
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 implies the return is a list of domains but does not specify the output structure, possible error cases, or required permissions. For a simple list operation, this may be adequate but lacks completeness without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions for any parameters (0% coverage), and the description only mentions the resource scope without elaborating on the optional env and region parameters or their filtering semantics. The parameter names are somewhat self-explanatory but not fully clear.
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 (list) and the resource (all domains for an app in a workspace). It distinguishes itself from the sibling tool listWorkspaceDomains, which presumably lists domains at the workspace level.
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 similar tools such as listWorkspaceDomains, nor are any prerequisites or context given for choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List an app's backups and its backup settings
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint and non-destructive behavior, so the description adds context by specifying that it returns both backups and backup settings. This is helpful given there is no output schema.
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 extremely concise, a single sentence, with no unnecessary words. It front-loads the action and resource effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description provides minimal but sufficient context about what is returned (backups and settings). However, it omits any mention of environment or region parameters, which could be relevant but are not critical for basic 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?
The schema has four parameters with zero descriptions, and the description does not elaborate on any of them (workspaceSlug, appSlug, env, region). Since schema coverage is 0%, the description fails to compensate, leaving parameter meaning unclear.
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 'an app's backups and its backup settings', making it unambiguous. It distinguishes from sibling tools like updateBackups and restoreBackup by focusing solely on listing.
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 is given about when to use this tool versus alternatives. The description implies it is for viewing, but it does not mention other related tools or edge cases where listing might not be appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetched live from GitHub; empty for apps whose source is not git. current is the branch the app deploys from.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses that data is fetched live from GitHub, that results are empty for non-Git sources, and defines the 'current' field. This goes beyond the read-only annotation by explaining actual behavior, though it omits potential network delay 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?
The description is extremely concise and to the point, with no redundant phrases. It conveys the essential behavior in two short sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description includes a useful edge case (empty for non-Git) and defines 'current', but lacks parameter details and any indication of response format. For a simple read-only tool this is acceptable, but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the four parameters (workspaceSlug, appSlug, env, region) beyond their implicit names. Since the schema covers them but the description adds no clarification, the semantic value is minimal.
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 indicates the tool fetches live data from GitHub and explains the meaning of 'current' in relation to the deployed branch. It is specific enough to distinguish from generic Git tools, though it could more explicitly state that it returns a list of branches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context about when results may be empty (non-Git sources) and that data is fetched live. However, it does not explicitly mention when to use this tool over related alternatives like getGitOverview or inspectSource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List TLS certificate statuses for app domains
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description's 'List' action aligns with a non-destructive read operation. No additional behavioral disclosures are needed.
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 information. It efficiently conveys 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?
The description provides a high-level purpose but does not specify the output structure or any additional context such as whether only current statuses are returned or historical data. Given the simplicity, this is acceptable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for any of the four parameters, and the tool description does not compensate by explaining them. Parameter names are somewhat self-explanatory, but env and region remain ambiguous without further context.
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 ('List') and the resource ('TLS certificate statuses for app domains'), which is specific and distinguishes it from related tools like listAppDomains or listWorkspaceDomains.
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 is clear about what the tool does but does not explicitly state when to use it versus alternatives. There is no direct comparison with sibling tools, so the agent must infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List an app's deploys
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with those. However, the description does not disclose any additional behavioral details like pagination or result limits, but given the simple read-only nature, the annotations suffice.
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 directly states the tool's function without unnecessary words or 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?
There is no output schema, and the description does not indicate what the response will contain. It also omits details about pagination, ordering, or any filtering beyond the parameters. The tool is too minimal to fully guide an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lists parameters but provides no descriptions. The description adds no explanation for workspaceSlug, appSlug, env, or region. While env has an enum, the meaning and usage of the parameters are not clarified.
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 'List an app's deploys' clearly states the action (list) and resource (deploys), and it is distinguishable from related tools like deployApp or rollbackDeploy. However, it does not specify what information is returned in the list.
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 such as streamActiveDeploy or streamDeployLogs. The description gives no context about filtering, ordering, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GitHub repositories
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| limit | No | ||
| workspaceSlug | Yes | ||
| installationId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description and annotations are consistent: 'Search' implies a read-only operation, and readOnlyHint=true confirms no side effects. However, the description gives no additional behavioral context such as whether results are paginated, sorted, or limited by the installationId, so it does not go beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and free of unnecessary wording. However, it is so brief that it sacrifices important context, which prevents a higher score for structure despite being well-formatted.
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 and no parameter descriptions, the description is far too incomplete for an agent to use confidently. It does not clarify what the returned data looks like, what the parameters mean, or how the tool fits into the broader GitHub integration workflow.
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 0% and the description does not explain any of the four parameters. While names like q and limit are somewhat self-explanatory, the required workspaceSlug and installationId are not, and no parameter descriptions are provided. The description fails to compensate for the complete lack of schema documentation.
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 'Search GitHub repositories' identifies a clear verb and resource, but it lacks essential scope: it does not mention that the search is scoped to a workspace or GitHub installation, which is implied by the required workspaceSlug and installationId parameters. It is distinguishable from sibling tools only by its name, not by a precise purpose statement.
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 like getGitOverview, linkGithubIntegration, or runGitAction. There is no mention of typical use cases, prerequisites, or whether this should be used before linking a GitHub integration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available regions
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the readOnlyHint and destructiveHint annotations, indicating a read-only operation with no side effects. It does not add beyond the annotations, but the annotations already provide sufficient 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, concise sentence with no unnecessary words. It front-loads the action and resource, making it immediately clear.
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 simplicity of the tool (no parameters, no output schema), the description is fully complete. It tells the agent exactly what the tool does without needing additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter information to explain. The description does not need to add meaning beyond the empty input schema, and the baseline for zero parameters is high.
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 'List available regions' clearly states the action (list) and the resource (regions). It is specific and easily distinguishable from sibling tools that list other resources like workspaces or templates.
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. While there are no direct alternatives for listing regions, the description lacks context such as prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available application templates
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns perfectly with the readOnlyHint annotation, indicating no side effects. It is a simple read operation, and the description does not introduce any conflicting behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the entire purpose without redundancy or fluff.
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 trivial nature of the tool (no parameters, simple listing action), the description provides all necessary context for an agent to invoke it correctly. No additional detail is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so no parameter descriptions are needed. The schema and description are fully consistent with zero 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 ('List') and the resource ('all available application templates'), making the tool's purpose unambiguous. No sibling tool overlaps with template listing, so it is easily distinguished.
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 straightforward usage: when you need to retrieve the set of application templates. Since no alternative tool exists, explicit when-not-to-use guidance is unnecessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List support tickets for the current user
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and destructiveHint, so the bar is lower. The description adds a behavioral scope ('for the current user') and clearly indicates a non-destructive list operation, with no contradiction to the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that uses no unnecessary words and focuses directly on the tool's action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description is reasonably complete: it identifies the resource and scope. It does not mention pagination, ordering, or return shape, but these are not critical for basic usage of a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the baseline is 4. The empty input schema provides no parameter meanings, and the description does not need to add parameter-specific details; it clearly states what entity is being listed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('support tickets') and a clear scope ('for the current user'), which distinguishes it well from sibling tools like getTicket, createTicket, updateTicket, addTicketMessage, and streamTicketMessages.
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 the tool by saying it lists tickets for the current user, but it does not explicitly contrast it with alternatives such as getTicket for a single ticket or createTicket for making a new one. Guidance is present by implication but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available service tiers
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate read-only and open-world behavior, and the description does not add extra behavioral details like return format, whether it includes pricing, or any side effects. It is consistent but adds minimal insight beyond the annotations and name.
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, direct sentence with no redundant words or complex structure. It is perfectly concise and easy to parse.
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 no parameters and no output schema, the description provides enough context to know what the tool does. It could mention the output format or the nature of 'service tiers' but the current information 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?
With zero parameters, the schema is fully covered and the description does not need to explain any inputs. The baseline for 0 params is 4, and the description is sufficient without parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('List') and resource ('all available service tiers'), making the tool's purpose immediately evident. It distinguishes itself from other list tools by the unique resource type, though it does not explicitly contrast with getPricing.
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 instead of alternatives such as getPricing or other list operations. It simply states the action without context or conditions, leaving the user to infer usage from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the authenticated user's API tokens
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and destructiveHint annotations already convey that this is a non-mutating, read-only operation. The description adds no further behavioral details, such as whether the full token value is returned or only metadata.
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, direct sentence with no unnecessary words, making it highly scannable and easy to parse.
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, the description is complete enough to indicate the tool's purpose. It does not describe the output shape, but no output schema is provided, and the intended use is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters and the schema fully reflects that with an empty properties object, so the description need not clarify parameter behavior.
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 identifies the verb ('List'), the resource ('API tokens'), and the scope ('authenticated user's'), making it distinct from sibling tools like createToken and revokeToken.
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 tool should be used when the user needs to view their own API tokens, but it does not explicitly contrast with related token tools (createToken, revokeToken) or mention any filtering or pagination options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List environment variables and credentials for an app
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already declares that this is a read-only operation, and the description ('List') is consistent. However, the description adds no additional behavioral context beyond the annotation, such as whether credentials are returned masked or the possibility of pagination.
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 or irrelevant information. It is well-structured and front-loaded with the verb and object, making it immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description provides minimal context. It does not mention whether the list is filtered by the optional env parameter, whether credentials are included in all cases, or what the response format looks like. Given the presence of sibling tools like getDbCredentials and revealVar, the meaning of 'credentials' is ambiguous.
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 0% (no parameter descriptions), and the description does not compensate. While workspaceSlug and appSlug are self-explanatory from their names, env and region are not explained. The description only hints at 'for an app' and does not clarify the meaning of env (production/preview/development) or region.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List'), names the resource ('environment variables and credentials'), and specifies the scope ('for an app'). This clearly distinguishes it from sibling tools like createVar, deleteVar, and updateVar, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives such as createVar, revealVar, or importVars. While the operation is implied by the name and verb, it does not state conditions like 'use this to retrieve all variables for an app' or mention that createVar is for adding new ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List volumes for an app instance
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description simply states 'list' which aligns with the readOnlyHint and non-destructive annotations, but it discloses no additional behavioral context (e.g., pagination, result format, potential errors). Since annotations already cover the read-only nature, the description adds minimal 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?
The description is a single, concise sentence with no superfluous words. It efficiently conveys the core purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation, the description is minimal and lacks context about the output format, filter behavior, or how the parameters affect the result. An agent would need additional information to know what 'volumes' includes and how to interpret the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lists four parameters (env, region, appSlug, workspaceSlug) with no descriptions, and the tool description does not explain any of them. With 0% schema coverage, the description fails to compensate by clarifying what each parameter means or which are required for the operation.
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 'List volumes for an app instance' clearly states a specific verb (list) and resource (volumes), with a context ('app instance') that distinguishes it from the sibling tool 'listWorkspaceVolumes'. However, it does not explicitly contrast with that sibling, so the differentiation relies on the inferred meaning of 'app instance'.
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 'listWorkspaceVolumes'. It does not mention conditions, prerequisites, or scenarios where one should be preferred over the other.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all domains in workspace
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the readOnlyHint and destructiveHint annotations. It does not add extra behavioral context beyond the obvious read-only nature of listing, but it also does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no redundant or unnecessary wording. It is direct and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with a single required parameter and no output schema, the description is sufficient. It does not mention return shape or pagination, but those are not necessary for basic invocation and 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?
The schema provides no description for workspaceSlug, and the tool description does not clarify its format, requiredness, or example values. The parameter name is somewhat self-explanatory, but the description adds little 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 action ('List'), the resource ('domains'), and the scope ('in workspace'). It is easy to distinguish from the sibling listAppDomains because it targets workspace-level domains rather than app-specific domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance about when to choose this tool over alternatives. The intended use is implied by the phrase 'all domains in workspace,' but it does not explicitly mention listAppDomains or other domain-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List workspace integrations and provider status
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the baseline safety profile is clear. The description adds no further behavioral context (e.g., side effects, rate limits, or whether it returns live or cached data), but given the simple read-only nature, this is acceptable.
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, compact sentence that conveys the essential purpose without unnecessary verbosity. It is well-structured and easy to parse.
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 basic list operation, the description is sufficient. It identifies what is listed (integrations) and includes 'provider status' as an important detail. It does not mention output format or whether pagination is supported, but given the absence of an output schema and the simplicity of the tool, this is not a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, workspaceSlug, is a string and required. The description does not elaborate on what the slug represents or any constraints, but the name is self-explanatory in the context of workspace-related tools. Schema coverage is effectively 100% since the parameter name is clear, so the 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 action ('List') and the resource ('workspace integrations'), and adds the extra detail of 'provider status', which distinguishes it from other list tools like listWorkspaceDomains or listWorkspaceMembers. It is immediately apparent what this tool does.
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 compared to sibling list tools, nor any conditions that would make it preferable. It does not mention alternatives or suggest scenarios. The agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List pending workspace invitations
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds the 'pending' scope. It does not disclose response shape, ordering, pagination, or authorization requirements, but for a simple read-only list this is a moderate gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It is minimal but appropriate for a tool of this simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only list, the description is close to sufficient, but it omits any detail about what fields are returned, how results are ordered, or where workspaceSlug comes from. Since there is no output schema, a bit more return/usage context would make it more robust.
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 0%, and the description does not explain what workspaceSlug should contain, how to obtain it, or how it affects the results. The parameter name is self-explanatory to a degree, but the description adds no 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 states a clear verb ('list') and a specific resource ('pending workspace invitations'). This distinguishes it from siblings such as revokeWorkspaceInvitation, acceptInvitation, declineInvitation, and getInvitation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives like getInvitation or listWorkspaceMembers. It also does not mention any prerequisites or context such as needing to review invitations before revoking or accepting them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List workspace members
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint=true and destructiveHint=false, so the read-only nature is transparent. The description adds no extra behavioral details (e.g., no mention of pagination or sorting), but it does not contradict the annotations. Given the annotation coverage, this is acceptable.
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 phrase that directly conveys the purpose. There is no fluff or redundant information, making it highly efficient for an agent to parse.
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 is sparse but adequate for a simple list operation. It does not mention the return format (e.g., list of member objects) or any filtering capabilities, but given the tool's simplicity and the absence of an output schema, an agent can likely infer the expected result. More detail could improve completeness but is not strictly 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?
The schema documents the single required parameter workspaceSlug, and the description adds no additional meaning. However, the parameter is self-explanatory within the context of workspace operations, so the schema coverage is sufficient. No extra semantics are needed.
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?
Tautological: description restates name/title.
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. It does not mention scenarios where this tool is preferred over others, nor does it reference prerequisites or related tools. An agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List workspaces for the authenticated user
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint: true and destructiveHint: false, so the description adds no new behavioral information. It does not mention side effects, rate limits, or any other behavioral details beyond what is already annotated.
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, clear sentence with no unnecessary words. It directly conveys the action and scope without any redundancy or ambiguity.
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 no output schema, the description sufficiently communicates what the tool returns (a collection of workspaces). No additional context is needed for an agent to understand the tool's purpose and expected result.
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 no parameters in the schema, so there is nothing for the description to explain. The baseline for zero parameters is 4, and the description does not introduce any confusion about inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing workspaces for the authenticated user. It specifies the verb ('list') and the resource ('workspaces'), which distinguishes it from other workspace-related tools like getWorkspace or createWorkspace.
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 minimal guidance on when to use this tool. It mentions 'for the authenticated user' which implies scope, but it does not explicitly contrast with alternatives like getWorkspace or createWorkspace, nor does it mention any conditions or prerequisites for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List storage volumes in workspace
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and destructiveHint annotations indicate no destructive side effects, and the description's 'list' wording aligns with read-only behavior. No additional side-effect disclosure is needed, though it doesn't mention output behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no unnecessary words and directly states the operation and scope.
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?
Adequate for a simple listing operation, but it omits details such as whether env/region are required filters, possible response format, or how this differs from the sibling listVolumes tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions and the tool description only clarifies workspaceSlug via 'in workspace'. The env and region parameters are not explained, so the description does not compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the resource (storage volumes) and action (list), and clarifies the scope as workspace. It does not explicitly differentiate from the sibling listVolumes tool, but the workspace qualifier provides enough purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like listVolumes or how to combine env/region filters. The description only states what it lists, not when it should be chosen.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the last 200 log lines of one container as {container, state, logs}; state is no-pod when nothing is running. serviceName is a compose service, or clone / build for an in-flight deploy's init steps. Sending Accept: text/event-stream instead follows the log live as server-sent events, one bare data: frame per line, which never completes on its own.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| serviceName | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses non-obvious behavior: the 'no-pod' state, the non-completing nature of the streaming variant, and the fact that it reads logs from one container. Combined with readOnlyHint and destructiveHint=false, the agent fully understands side effects and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact but dense, using three sentences to convey purpose, output shape, state handling, special serviceName values, and streaming behavior. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the absence of an output schema, the description covers the return format, container scope, state behavior, special serviceName values, and the streaming alternative. It provides enough context for an agent to use the tool correctly without additional lookups.
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 description provides meaningful semantics for serviceName, but leaves env and region unexplained. Since the schema has no per-parameter descriptions, the tool description only partially compensates, covering one of five parameters. The remaining ones are inferred from enums or naming, but not explicitly described.
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 reads and returns the last 200 log lines of a single container, with an explicit output shape. It also distinguishes itself from streaming via Accept header and clarifies special serviceName values, making its purpose unambiguous relative to 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?
It provides concrete guidance on when to use the default behavior (fetch last 200 lines) vs. streaming with Accept: text/event-stream, and explains special serviceName values for in-flight deploy init steps. This gives the agent clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Redeploy an app (refresh code + roll pods)
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description does not need to establish mutability. The parenthetical 'refresh code + roll pods' adds some behavioral detail, though it does not describe side effects, downtime, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. The core action and mechanism are stated compactly, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with four parameters, no output schema, and several closely related sibling tools, the description is too sparse. It does not clarify required identifiers, environment/region behavior, or how this differs from deployApp and rollbackDeploy.
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 0%, and the description provides no parameter-level guidance. It does not explain workspaceSlug, appSlug, env, or region, leaving the agent to rely solely on the schema field names and the single enum.
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 clear verb and resource ('Redeploy an app') and adds a useful parenthetical ('refresh code + roll pods') that conveys the operational mechanism. It does not explicitly differentiate from sibling tools like deployApp or rollbackDeploy, which prevents a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance about when to use redeployApp versus deployApp, rollbackDeploy, or listDeploys. The word 'redeploy' implies an existing app, but the context is not stated and 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.
Overwrites the app's current volume contents with the snapshot. There is no undo.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| backupId | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It explicitly discloses the destructive overwrite behavior and the lack of undo, going beyond the destructiveHint annotation by describing the exact effect on volume contents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler, front-loading the core action and the critical warning.
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 conveys the essential destructive effect but lacks surrounding context such as parameter meanings, any preconditions, or what happens after the restore. It is adequate but minimal.
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?
None of the five parameters (workspaceSlug, appSlug, backupId, env, region) are explained in the description, and the schema has no descriptions. The agent is left to infer their meanings from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: overwriting the app's current volume contents with a snapshot. This is specific and distinguishes it from backup listing or deployment rollback 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 provides no guidance on when to use this over sibling tools such as rollbackDeploy or listBackups. It only warns that there is no undo, which is cautionary rather than usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reveal the decrypted value of a secret variable
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| varId | Yes | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint: true and destructiveHint: false annotations already communicate the safety profile. The description adds the useful behavioral detail that decryption occurs, but does not disclose additional context such as security implications of revealing secrets or any rate limits or auth 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?
The description is a single sentence, highly concise, and front-loaded with the key action verb 'Reveal' at the start. No unnecessary words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is security-sensitive (revealing secrets) and has five parameters with no schema descriptions, yet the description provides no context about return value shape, security warnings, or parameter relationships. The description is too minimal to fully guide an agent given the tool's complexity and sensitivity.
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 0% (no parameter descriptions in the schema), which is below the 50% threshold requiring compensation from the description. The description does not mention any of the five parameters (workspaceSlug, appSlug, varId, env, region), leaving the agent with no semantic guidance for parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Reveal') and resource ('decrypted value of a secret variable'), clearly distinguishing it from sibling tools like listVars (which presumably lists variable metadata without decrypting values), createVar, updateVar, and deleteVar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'decrypted value' implies the tool is used when the actual secret value is needed, contrasting with listVars which likely returns metadata only. However, it does not explicitly name an alternative sibling tool or state conditions for choosing this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revoke an API token
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructiveHint=true and readOnlyHint=false, which correctly convey that this operation is destructive and not read-only. The description adds no further behavioral details beyond 'revoke', but this is consistent with the annotations and not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no unnecessary words. It is concise and directly states the tool's purpose, fitting the simple one-parameter interface.
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 has minimal context: it does not explain what the 'id' represents, what happens upon revocation (e.g., permanent invalidation), or what outcomes are expected. While the destructive annotation helps, the description alone is insufficient for an agent to fully understand the operation's effects.
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 a single required parameter 'id' with no description, and the tool description does not explain what 'id' refers to. With 0% schema coverage and no additional context, the meaning of 'id' is entirely unspecified.
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 'Revoke an API token' clearly states the action (revoke) and the resource (API token), distinguishing it from sibling tools like createToken and listTokens. It is specific and 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 guidance is provided on when to use this tool versus alternatives. It does not mention that it should be used to invalidate a token, nor does it warn against using it for other operations. The agent is left without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revoke workspace invitation
| Name | Required | Description | Default |
|---|---|---|---|
| invitationId | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true and readOnlyHint=false, which covers the safety profile. The description adds no extra detail about side effects, permissions, or reversibility, but since the annotations carry that information, a baseline score of 3 is appropriate.
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, clear phrase with no unnecessary words or redundancy. It is perfectly sized for a simple tool action and easy to parse quickly.
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 context about the consequence of revocation (e.g., whether it is irreversible, whether it only affects pending invitations, or if it notifies the invitee). Given there is no output schema, this additional context would help the agent understand the full impact of the action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for workspaceSlug or invitationId, and the tool description does not clarify their meaning or expected format. With 0% schema coverage, the description should compensate but it is completely silent on parameters, offering no semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tautological: description restates name/title.
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?
There is no guidance on when to use this tool versus alternatives such as declineInvitation or deleteWorkspaceInvitation (if it existed). The description does not mention scenarios, prerequisites, or typical use cases, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Needs a running, build-backed app whose target image is still in the registry. Restarts every service in the instance, database included.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| deployId | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly discloses that the operation restarts every service, including the database, which goes beyond the destructiveHint annotation. It also implies a change to the deployed image. However, it does not mention potential downtime or whether a new deploy record is created, leaving some behavioral details unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, directly states the precondition and the action, and contains no filler or redundant information. It is efficiently structured and easy to parse.
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 gives the core action and a key precondition, it lacks details about the parameters (especially deployId and env) and any output or side effects beyond restarting services. For an agent to use the tool correctly, it would need to know that deployId likely refers to the target deployment to roll back to, which is not explicitly stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for the five parameters, and the description does not explain what workspaceSlug, appSlug, deployId, env, or region represent. The term 'deployId' is mentioned indirectly via 'target image' but never explicitly defined, leaving the agent to infer parameter meanings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title 'Rollback Deploy' and description 'Restarts every service in the instance' clearly state the action and resource, distinguishing it from sibling deploy-related tools like redeployApp or createAppDeploy. The precondition about the target image being in the registry further clarifies its specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a precondition ('Needs a running, build-backed app whose target image is still in the registry') but does not explicitly state when to use this tool versus alternatives like redeployApp or deployApp. It implies a rollback scenario but lacks direct guidance on choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs over a real protocol driver, not a shell, and executes whatever is sent — including writes and DDL. Redis and MongoDB take their own command syntax rather than SQL.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is transparent about the tool being able to execute writes and DDL, which aligns with the destructiveHint annotation. It does not hide the potentially destructive nature, though it could mention more about side effects or safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and to the point, but the phrase 'real protocol driver, not a shell' is slightly confusing and could be simplified. Overall, it is appropriately sized.
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 this is a potentially destructive tool that executes arbitrary commands, the description lacks important context such as expected output, required request shape, or risks. The annotations provide a warning, but the description alone is incomplete.
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 very low (20%). The description does not explain key parameters like sql, component, schema, env, or region. Only requestBody has a generic description, leaving most parameter semantics unclear.
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 that the tool executes arbitrary database commands, including writes and DDL, and distinguishes it from a shell. However, the phrase 'real protocol driver, not a shell' is somewhat ambiguous and could be clearer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a hint about Redis and MongoDB command syntax but does not explicitly state when to use this tool versus related DB tools like getDbSchema or getDbCredentials. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One action per call: discard, stage, unstage, commit, checkout, merge, rebase, revert, cherry, pull or push. Commits live in the container and die with it unless pushed.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the important behavioral note that commits reside in the container and vanish unless pushed, which is beyond the destructiveHint annotation. It also implies mutating operations via the listed actions, but does not elaborate on all side effects (e.g., discard intentionally removes changes).
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 extremely concise and front-loads the list of actions in a single sentence. It avoids redundant wording and efficiently conveys the core behavior and the critical caveat about commit persistence.
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 complex nested oneOf schema with action-specific requirements, the description is far too terse. It does not explain which parameters are needed for each action, nor does it address the destructive nature of certain operations (e.g., discard, revert). The agent would need to deeply inspect the schema to use the tool correctly, and the description provides negligible context to aid that process.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only 20% description coverage (only requestBody is described). The tool description lists valid action values but does not explain the required workspaceSlug, appSlug, env, or region parameters, nor how the requestBody varies per action. This leaves too much for the agent to infer from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly lists all supported actions (discard, stage, unstage, commit, checkout, merge, rebase, revert, cherry, pull, push), making its purpose unmistakable. It clearly distinguishes from sibling read-only tools like getGitDiff or getGitOverview by focusing on mutating git state.
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 some guidance (e.g., 'One action per call' and the ephemeral nature of commits) but does not explicitly state when to use this tool versus alternatives. It lacks explicit contrasts with sibling tools like inspectSource or getGitDiff, leaving users to infer the intended use case from the action list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enabling it requires a verified phone number.
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose side effects, state changes, or requirements beyond a phone number. Annotations indicate destructive=true and readOnly=false, but the description adds no behavioral detail about what setting MFA entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and contains no fluff, but the single sentence is more of a caveat than a functional description. It is short but sacrifices necessary clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks essential context: no output schema, no explanation of the request body's purpose, no mention of verification flow, and no indication of what happens when MFA is set. The description is incomplete for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema defines a boolean 'mfaEnabled' inside a requestBody, but the description does not explain the meaning of this field. It is unclear whether true enables MFA, false disables it, or if other semantics apply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title 'Set Mfa' is vague, and the description only states a precondition ('Enabling it requires a verified phone number') without explicitly saying what the tool does. It does not clearly indicate that this sets or updates the MFA enabled/disabled state.
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 verifyPhone or startPhoneVerification. The description mentions a precondition but does not explain the intended workflow or when this should be called.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a clientSecret that Stripe's payment element exchanges for a saved card in the browser. The secret alone cannot charge anything or read existing cards, and it is scoped to the caller's own Stripe customer.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions what the tool does not do (cannot charge or read cards) but omits any side effects such as creating a setup intent or modifying state. Given destructiveHint is true, the absence of side-effect disclosure is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two focused sentences. It is well-structured with no redundant information, and the security note adds value without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description provides sufficient context: what it returns, the scope, and a security consideration. It does not mention error conditions or authentication, but these are commonly assumed. Overall, it is complete enough for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the baseline is 4. The description does not need to add parameter details, and it does not claim any incorrect information about inputs.
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 returns a clientSecret for Stripe's payment element, with specific context about saved cards and customer scoping. It is specific enough to understand the tool's purpose, though it does not explicitly differentiate 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 usage context (for saving cards in the browser) and provides a caution about the secret's limitations, but it does not explicitly state when to use this tool versus alternatives or include any prerequisites. Guidance is present but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a verification code to a phone number
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations include 'destructiveHint: true', the description does not elaborate on side effects such as sending an SMS, potential costs, or rate limits. It only states the action without disclosing any behavioral nuances beyond the annotation.
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 filler or redundant information, achieving high clarity with minimal text.
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, the description covers the core action, but lacks details on phone number formatting or what the response will be. Given the absence of an output schema, this gap is notable but not critical for basic 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?
The schema only provides a 'phone' string with length constraints, but no description of format (e.g., E.164, country code). The tool description does not supplement this, leaving the parameter's expected format and semantics unclear.
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 ('Send a verification code') and the target ('a phone number'), making the purpose unambiguous. It distinguishes from the sibling 'verifyPhone' by implying the start of the process rather than verification itself.
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 'verifyPhone'. It does not mention prerequisites, expected outcomes, or any conditions that would make this tool the appropriate choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns one {ts, deploy} frame: the active deploy if one is running, otherwise the most recent, and deploy is null when the app has never deployed. Sending Accept: text/event-stream instead follows it live, a frame every two seconds, closing after one terminal frame.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description richly discloses behavior beyond the readOnlyHint/openWorldHint annotations: the 2-second polling interval, terminal frame closure, the active-vs-most-recent fallback, the null case for never-deployed apps, and the behavior switch based on the Accept header. This is exemplary transparency for an agent deciding whether and how to invoke the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler. The first sentence front-loads the primary return contract; the second adds the streaming variant. Every clause carries meaning.
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 there is no output schema, the description covers the frame shape ({ts, deploy}), the nullable deploy case, the streaming mode, interval, and termination — quite complete for an agent deciding to call it. The main gaps are parameter semantics (scored separately) and the lack of any detail about the deploy object's fields, which an agent might need to plan downstream actions.
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 0% — none of the four parameters (workspaceSlug, appSlug, env, region) are explained. Critically, the description does not clarify whether env or region filters which deploy is considered 'active' or 'most recent', leaving a significant ambiguity that the description must compensate for but does not.
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 resource being targeted (the active deploy, or most recent if none is running, or null if never deployed) and the streaming behavior, which distinguishes it well from siblings like listDeploys and streamDeployLogs. The verb 'Returns' and the explicit frame shape make the purpose concrete, though it could more explicitly state that it is for monitoring deploy progress.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives implicit usage guidance by explaining the one-shot versus streaming mode via the Accept: text/event-stream header, and the 2-second interval/terminal frame behavior. However, it does not explicitly contrast with sibling tools such as listDeploys, streamDeployLogs, or streamAppStatus, so an agent must infer when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns one metrics reading; network and requestsPerSec are null until a second sample exists, so they are null on a one-shot read. Sending Accept: text/event-stream instead follows usage live, a frame every five seconds, which never completes on its own.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnlyHint annotation by explaining that `network` and `requestsPerSec` are null on the first sample, and that streaming emits frames every five seconds and never completes on its own. This is valuable behavioral detail not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, using just two sentences to convey both the one-shot behavior and the streaming alternative. No unnecessary words or repetition; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key operational aspects: the default one-shot read, the null fields on first sample, and the streaming option with its interval and non-terminating nature. It does not specify the output format or schema, but given the simplicity of the operation and the absence of an output schema, the description is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no explanation of the parameters (env, region, appSlug, workspaceSlug), and the schema itself has zero description coverage. The agent is left to infer the meaning from parameter names alone, which is insufficient given the lack of any parameter-level guidance in either the description or 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's purpose: it returns app metrics readings, with the ability to stream live usage via an Accept header. This distinguishes it from other streaming tools like streamAppStatus or streamDeployLogs by focusing on metrics data.
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 specific usage guidance by explaining the one-shot vs. streaming behavior and mentioning the Accept: text/event-stream header for live streaming. It does not explicitly contrast with alternative tools, but the name and context make the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns one status frame. Sending Accept: text/event-stream instead follows the status live, a frame every five seconds, which never completes on its own.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false). The description adds genuine behavioral value by disclosing the header-driven mode switch and the critical fact that the streaming variant never completes on its own — essential for an agent to avoid waiting indefinitely. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with the primary single-frame behavior front-loaded, followed by the streaming variant. Every clause earns its place with no fluff or repetition of the title.
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 one-shot vs streaming duality is well explained, which is the tool's most complex behavioral aspect. However, with no output schema present, the description should clarify what a 'status frame' contains and does not. Parameter semantics are also left to inference, leaving moderate gaps for an agent to fully understand invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden for parameter explanation, yet it mentions none of the four parameters (workspaceSlug, appSlug, env, region). The env enum and obvious slug names offer some self-evidence, but the description adds zero parameter context to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Returns one status frame') that clarifies the tool returns a snapshot of app status rather than a continuous stream, distinguishing it from streaming siblings like streamAppMetrics and streamActiveDeploy. The 'status frame' term is somewhat vague about what fields it contains, but the core purpose is clear and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on the one-shot vs live invocation via the Accept header toggle, including the useful detail that the stream never completes on its own. However, it does not address when to choose this tool over alternatives like streamAppMetrics or streamActiveDeploy, nor mention any prerequisites for using it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns one {kind:"snapshot", log, status} frame — the whole log so far, not a delta: the stored log for a finished deploy, the live build pod's log for the in-flight one. Sending Accept: text/event-stream instead re-sends a growing snapshot every two seconds; a finished deploy sends one frame and closes, the in-flight one keeps the connection open after it ends, so close it yourself once a frame carries final: true.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| deployId | Yes | ||
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral detail beyond annotations: the whole-log-not-delta behavior, the streaming re-send every two seconds, the connection-closing rule, and the `final: true` flag. This is rich, non-contradictory context that an agent needs to interact correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. The core behavior is front-loaded, followed by the streaming alternative and connection-handling details. Every clause adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a streaming tool with no output schema, the description covers the essential operational details: frame structure, streaming behavior, connection lifecycle, and the `final` flag. It is complete enough for an agent to call the tool correctly and interpret the stream. No critical information 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 0%, so the description should compensate for parameter meaning. It does not explain `env`, `region`, or the required slugs beyond their names, which are fairly self-explanatory. The description focuses on behavior rather than parameter semantics, providing only minimal value over the schema's names and enum for `env`.
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 returns deploy log frames with a specific structure (`{kind:"snapshot", log, status}`) and explains the snapshot vs delta nature. It distinguishes from sibling streaming tools by focusing on deploy logs and the two modes (single snapshot vs growing stream). The verb 'Returns' is specific, and the resource is 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?
It gives clear context on when to use this tool (to retrieve deploy logs) and describes the two modes (single frame vs streaming) with explicit instructions on when to close the connection. However, it does not explicitly name alternative tools or state when not to use it, leaving exclusions to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns one frame. Sending Accept: text/event-stream instead follows the thread live, every 2.5 seconds, which stops only when the ticket disappears.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate read-only and non-destructive behavior, and the description aligns with this by only describing data retrieval and streaming. It transparently states the streaming termination condition (when ticket disappears), but does not mention any potential side effects or lack thereof beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two short sentences. It is well-structured and avoids unnecessary fluff, though the brevity slightly reduces clarity due to the lack of explicit context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides basic operational context (frame vs. streaming, termination condition) and is complemented by the tool name and annotations. However, it lacks details on output format, the meaning of 'frame', and how this relates to other ticket-related tools, leaving some gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter 'id' of type string, but neither the description nor the schema provides any explanation of what this ID represents. The tool name suggests it is a ticket ID, but this is not stated, leaving the parameter semantics ambiguous and undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it returns a frame and can stream the thread live, clearly indicating the tool's purpose. However, it does not explicitly mention 'messages' or define what a 'frame' is, though the tool name provides strong context.
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 explains that sending an 'Accept: text/event-stream' header enables live streaming, which is a specific usage instruction. It also mentions that streaming stops when the ticket disappears, providing operational guidance. It does not compare with similar tools like getTicket or listTickets, but the usage hint is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transfer an app to another workspace
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description simply says 'Transfer' and the annotations already indicate destructive behavior. It does not disclose additional side effects such as removal from the source workspace, impact on deployments, or whether the transfer is reversible.
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 clear, front-loaded sentence with no unnecessary words or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has multiple parameters, a nested request body, and no output schema, but the description offers no additional context about how to construct the call correctly or what to expect afterward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has very low description coverage (20%) and the description does not explain any parameters. There is no clarification of workspaceSlug, appSlug, region, env, or the required nested targetWorkspaceSlug in requestBody.
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 'Transfer an app to another workspace' clearly states a specific action, resource, and destination. It distinguishes this tool from sibling tools such as transferWorkspaceOwnership or deployApp.
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, nor any context about prerequisites, target workspace requirements, 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.
Transfer workspace ownership
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds nothing beyond that. It does not explain the consequences of ownership transfer, what happens to the current owner, or any side effects. With annotations present, the bar is lower, but the description contributes no additional behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single phrase with no wasted words, but it is under-specified rather than concise. It lacks any front-loaded critical information like side effects or prerequisites, making it too minimal for a destructive operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a destructive tool with nested parameters and no output schema. The description provides no information about what happens to the workspace, the old owner, or the new owner, nor does it explain any required authentication or authorization. It is completely inadequate for an agent to safely invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% (workspaceSlug lacks a description, requestBody has a generic description). The tool description mentions no parameters at all, so it fails to compensate for the schema's incomplete parameter documentation. An agent gets no help understanding what targetUserId means or how it should be provided.
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?
Tautological: description restates name/title.
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?
There is no guidance on when to use this tool versus alternatives, no prerequisites, no mention of required permissions, and no exclusions. The description is purely declarative with zero contextual cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an app (name / status / version)
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose side effects, merge vs replace behavior, or any destructive implications beyond the annotation. Since destructiveHint is true, more transparency about partial updates or irreversibility would be expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and to the point, but the inaccuracy regarding 'version' slightly detracts. It is structured as a single sentence listing a few potential fields, which is acceptable but not highly organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the schema (nested objects, multiple enums, optional vs required fields), the description is minimal. It does not explain the purpose of the scale, tracking, or autoDeploy fields, nor the behavior when optional fields are omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only the requestBody parameter has a description ('The JSON request body'), while all other parameters (workspaceSlug, appSlug, env, region) lack explanations. The schema provides enums and constraints but no field-level descriptions, and the 'version' mention in the description does not map to any schema parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an app, using the verb 'Update' and resource 'app'. However, it mentions 'version' which is not present in the schema, causing slight confusion about the actual updatable fields.
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 createApp, deleteApp, or redeployApp. The description only gives a generic update statement without differentiating scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn managed backups on or off and set the daily window
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the agent knows this mutates state and is potentially destructive. The description adds that it affects backup toggling and the window, which is useful context, but it doesn't disclose side effects (e.g., impact of turning off backups) or any permission requirements. With annotations covering the safety profile, this is 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?
A single sentence that is concise and front-loaded with the core action. No filler or redundant phrasing; 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 5 parameters, no output schema, and a low schema coverage, the description is incomplete. It does not explain required fields, the meaning of environment/region, or the implications of disabling backups. An agent calling this tool would need to infer too much from parameter names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only requestBody has a description), so the tool description must compensate. It loosely maps 'on or off' to the 'enabled' field and 'daily window' to 'window', but it gives no explanation for env, region, appSlug, or workspaceSlug. An agent cannot infer their purpose or required formats from the description alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: toggling managed backups on/off and setting the daily window. It uses specific verbs ('turn on or off', 'set') and a specific resource ('managed backups'), distinguishing it from siblings like listBackups (read) and restoreBackup (restore).
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. It does not mention that this is the write operation for backup settings, nor does it note any prerequisites or exclusions. Siblings like listBackups and restoreBackup exist, but no comparison or selection criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a domain configuration
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| region | No | ||
| appSlug | Yes | ||
| domainId | Yes | ||
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutating/destructive nature is known. The description adds no extra behavioral context (e.g., what gets changed, side effects, permissions), so it provides minimal value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence) but under-specified for a tool with six parameters and a nested object. It lacks any structure or front-loaded key information, making it insufficiently informative.
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 mutation tool with no output schema, low parameter coverage, and no guidance on return values, side effects, or usage, the description is grossly incomplete. An agent cannot reliably invoke this tool correctly based on the provided information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, and the description does not explain any of the parameters (workspaceSlug, appSlug, domainId, env, region, requestBody). It fails to compensate for the sparse schema, leaving the agent without clues about parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Update') and resource ('domain configuration'), which is specific enough to distinguish from createDomain and deleteDomain. It doesn't list the updatable fields, but the core action is 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?
There is no guidance on when to use this tool versus alternatives like createDomain or deleteDomain. The description simply states the action without any context about prerequisites, scenarios, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update notification preferences for the current user
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a mutation, which aligns with readOnlyHint=false and destructiveHint=true, but it does not go beyond the annotations to describe side effects, idempotency, or potential impacts of changing preferences.
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 clear sentence with no redundant wording, making it concise and 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 preference-update tool with no output schema, the description is mostly complete. It could mention the effect or the fact that this modifies the authenticated user's settings, but the current wording is sufficient for basic 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?
The input schema already covers all parameters with self-explanatory boolean property names, and the description adds no additional semantic detail beyond the schema. With high schema coverage, 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 the action ('Update'), the resource ('notification preferences'), and the scope ('for the current user'), making it easy to distinguish from the sibling getNotificationPreferences 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?
The description does not explicitly explain when to use this tool versus alternatives such as getNotificationPreferences, nor does it mention any preconditions or related operations. It relies on the tool name to imply the read/write distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update or set the password for the current user
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructiveHint=true, and the description states 'Update or set' which implies a change. However, the description does not disclose any side effects, such as whether the change invalidates existing tokens or sessions, or whether the currentPassword is actually required for verification (schema lists it as optional). Since the annotations cover the destructive nature, the description adds only minimal behavioral 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, concise sentence that conveys the core purpose without any unnecessary verbiage. It is well-structured and easy to parse, making it efficient for an agent to process.
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 tool is simple, important context is missing: there is no mention of output or return value (no output schema), no mention of whether the operation requires authentication, and no indication of potential consequences like session invalidation. The description is adequate for a trivial mutation, but given the security-sensitive nature, more context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema includes newPassword (required) and currentPassword (optional), but the description provides no explanation of their purpose or constraints. There is no mention that currentPassword might be needed for security verification, nor any clarification of the password strength requirements beyond the minLength/maxLength in the schema. With parameter coverage at 0% in the description, this is a significant gap.
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 ('Update or set the password') and the target resource ('for the current user'). It is distinct from sibling tools like checkPassword (which likely validates password strength) and setMfa (which manages multi-factor authentication), so an agent can easily identify when this tool is appropriate.
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 provide explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., being authenticated) or caveats (e.g., that changing the password may invalidate existing sessions). The agent must infer usage from the tool name and schema, which is insufficient for a security-sensitive operation like password changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update ticket status or mark as read
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| requestBody | No | The JSON request body. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations indicate readOnlyHint=false and destructiveHint=true, the description does not disclose the potential side effects of updating a ticket, such as whether changing status to 'resolved' closes the ticket or has additional consequences.
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 unnecessary detail, making it easy to parse and understand quickly.
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 and the schema covers the main fields, but the description does not address the destructive hint or explain the effects of changing status, which leaves some ambiguity for an agent deciding whether to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides types, enums, and a const for the main fields, but the description adds little beyond naming 'status' and 'read'. The 'id' parameter's meaning is inferred from context rather than explicitly documented.
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 operation: updating a ticket's status or marking it as read. It distinguishes the tool from sibling tools like addTicketMessage and getTicket, though it could be slightly more explicit about the allowed status values.
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. It does not mention prerequisites, typical scenarios, or distinguish it from related ticket actions such as adding a message or creating a ticket.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an environment variable or credential value
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | ||
| varId | Yes | ||
| region | No | ||
| appSlug | Yes | ||
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=true, so the agent knows this is a mutating operation with potential side effects. The description adds minimal context beyond the word 'update' and does not describe permission requirements, reversibility, or the effect on running applications. It does not contradict annotations, so a neutral score of 3 is appropriate given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff, which is efficient. However, it is so minimal that it lacks substance needed for effective agent guidance. It earns a middle score because it is concise but not adequately informative.
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 mutation tool with six parameters, a nested request body, no output schema, and destructive annotations, this description is severely lacking. It does not explain the request body structure, the meaning of env/region, or the consequences of updating a secret. An agent cannot correctly invoke this tool without additional external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17% (only the requestBody property has a description). The description provides no explanation for parameters like env, region, varId, or the isSecret field. It fails to compensate for the low coverage, leaving most parameters semantically undocumented.
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 (update) and the resource (environment variable or credential value). It is specific enough to differentiate from createVar and deleteVar, though it does not explicitly name alternatives. The verb and resource are clear and 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 guidance is given on when to use this tool versus alternatives like createVar or deleteVar. It does not mention prerequisites such as the variable already existing (varId required) or when updating is appropriate (e.g., changing a secret vs. a non-secret). The description implies usage but provides no explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a workspace (requires full scope)
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. | |
| workspaceSlug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this as destructive and non-read-only, and the description says 'requires full scope,' but it does not disclose the actual effects of the update, whether it replaces or merges fields, or what side effects may occur. There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single terse sentence with no redundant wording. However, the brevity comes at the cost of important contextual information that other dimensions require.
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 is far too sparse: it omits updateable fields, request-body semantics, return behavior, error conditions, and detailed permission requirements. An agent would not have enough information to safely decide whether and how to call this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description gives no meaning for workspaceSlug or requestBody, and the schema only provides constraints like patterns and max lengths. Nested fields such as paymentMethodId, hues, and iconUrl are left unexplained, so the agent cannot infer their purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the verb 'Update' and the resource 'workspace', which distinguishes it from sibling tools like createWorkspace and deleteWorkspace. The scope note adds some clarity, though it does not mention what aspects of the workspace can be updated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives such as createWorkspace or getWorkspace. It does not describe the intended use case, what fields are typically modified, or when it should be avoided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Confirm a phone number with the code that was sent
| Name | Required | Description | Default |
|---|---|---|---|
| requestBody | No | The JSON request body. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as non-read-only and destructive, and the description adds no further behavioral context. It does not disclose whether the code is consumed, whether verification is irreversible, or what happens on failure, leaving the agent without important side-effect 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, front-loaded sentence with no filler. Every word contributes to understanding the tool's core 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?
For a simple verification tool the description covers the basic action, but it omits the expected relationship with startPhoneVerification and does not clarify that the required fields live inside a nested requestBody object. With no output schema, some information about the outcome 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%, so the schema already documents the requestBody structure and the required phone and code fields. The description merely restates 'phone number' and 'code' without adding format, sequencing, or other semantic details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Confirm') and resource ('a phone number') with the code, making the tool's action unambiguous. It also clearly distinguishes verifyPhone from the sibling startPhoneVerification by focusing on the confirmation step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'with the code that was sent' implies this is used after a verification code has been delivered, but it never explicitly states 'use after startPhoneVerification' or mentions any exclusions. The usage context is implied rather than directly instructed.
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.
v0.5.1acceptInvitationaddTicketMessagechangeBillingPlancheckPasswordcheckWorkspaceSlugcreateAppDeploycreateDomaincreateS3SessioncreateSshSessioncreateTicketcreateTokencreateVarcreateWorkspacecreateWorkspaceInvitationdeclineInvitationdeleteAppdeleteDomaindeleteVardeleteWorkspacedeployAppdisconnectGithubIntegrationendS3SessionexecCommandgetAccountBillinggetAppServicesgetDbCredentialsgetDbSchemagetGitDiffgetGitOverviewgetInvitationgetMegetNotificationPreferencesgetPricinggetTicketgetUserBillingStategetVolumeKeysgetWorkspacegetWorkspaceBillingimportVarsinspectSourcelinkGithubIntegrationlistAppDomainslistBackupslistBrancheslistCertStatuseslistDeployslistGithubReposlistRegionslistTemplateslistTicketslistTierslistTokenslistVarslistVolumeslistWorkspaceDomainslistWorkspaceIntegrationslistWorkspaceInvitationslistWorkspaceMemberslistWorkspaceslistWorkspaceVolumesreadServiceLogsredeployApprestoreBackuprevealVarrevokeTokenrevokeWorkspaceInvitationrollbackDeployrunDbQueryrunGitActionsetMfastartCardSetupstartPhoneVerificationstreamActiveDeploystreamAppMetricsstreamAppStatusstreamDeployLogsstreamTicketMessagestransferApptransferWorkspaceOwnershipupdateAppupdateBackupsupdateDomainupdateNotificationPreferencesupdatePasswordupdateTicketupdateVarupdateWorkspaceverifyPhoneScored across 88 tools
Most tools have clear distinct purposes, but a few pairs like 'deployApp' and 'createAppDeploy' have overlapping functionality that could cause misselection. The descriptions help clarify, but the sheer number of tools increases the chance of confusion.
Tool names generally follow a verb_noun pattern, but the verbs are inconsistent (list, get, create, update, set, check, stream, etc.) and some pairs like 'verifyPhone' vs 'startPhoneVerification' use different structures. The naming is readable but not highly uniform.
With 88 tools, this server is far beyond a typical well-scoped set (3-15) and even exceeds the 'extreme mismatch' threshold of 50+. The sheer volume makes it overwhelming and likely to contain redundant or overly granular operations.
The toolset appears to cover a broad range of CRUD and lifecycle operations across apps, workspaces, billing, and security. While some gaps might exist (e.g., no explicit 'deleteToken' but 'revokeToken' serves that purpose), the coverage seems comprehensive for the domain.
Deploy and manage your apps, databases, storage, and scheduled jobs from your AI agent
Deploy full-stack apps (Postgres, Redis, S3, workers, backups) from Claude or curl. 59 MCP tools.
Deploy a GitHub repo to a live HTTPS URL from your AI tool; read logs, set variables, resize apps.
Run AI models, create deployments, and manage predictions via cloud API
