This railway-mcp server allows you to manage your Railway.app infrastructure through natural language commands.
Authentication: Configure and manage Railway API tokens
Project Management: List, create, delete, and get information about projects and environments
Service Management: Create, list, update, delete, and restart services from GitHub repos or Docker images
Deployment Management: List, trigger, monitor deployments, and view logs and statuses
Database Management: Deploy pre-configured databases from templates or custom Docker images
Environment Variables: List, set, delete, bulk update, and copy variables between environments
Domain Management: List, create, update, and delete custom domains for services
Volume Management: Create, list, update, and delete persistent volumes for services
TCP Proxy Management: Create, list, and delete TCP proxies for services
Allows to create Railway services from Docker images.
Mentioned as a recommended companion MCP server to use alongside the Railway MCP server.
Allows to create Railway services from GitHub repositories and is mentioned as a recommended companion MCP server.
Allows to manage Railway.app infrastructure, including project management, deployment management, service management (creating from GitHub repos or Docker images), variable management, service network management, and volume management.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@railway-mcp deploy my backend service from the main branch"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for integrating with the Railway.app platform.
Related MCP server: Railway MCP Server
Status | Meaning |
ā | Complete |
š§šØā³ | Being Built or Needs Testing |
ā | Not Built at the moment |
ā Authentication with Railway API tokens
ā Project management (list, info, delete)
ā Deployment management (list, restart)
ā Service management (create from GitHub repo or Docker image, list)
ā Variable management (list, create/update, delete)
ā Service Network management
ā Volume management
ā Full support for all templates
š§šØā³ Database template support
Automatic database and networking workflows
š§šØā³ Most commonly used workflows
ā Automatic GitHub repository linking for services
Node.js 18+ (for built-in fetch API support)
An active Railway account
A Railway API token (create one at https://railway.app/account/tokens)
This MCP server is designed to work with MCP Clients like:
Claude for Desktop | ā Battle-Tested
Cursor | ā Needs Testing
Cline | š§šØā³ Needs Testing
Windsurf | š§šØā³ Needs Testing
Other MCP Clients | š§šØā³ Needs Testing
To install railway-mcp automatically, we recommend using Smithery
Claude Desktop
npx -y @smithery/cli install @jason-tan-swe/railway-mcp --client claudeCursor
npx -y @smithery/cli@latest run @jason-tan-swe/railway-mcp --config "{\"railwayApiToken\":\"token\"}"Head to your cursor settings and find the MCP section
Click 'Add new MCP server'
Name it however, you like, we recommend railway-mcp for better clarity
Paste this command into the 'Command' section, where is your accounts Railway token:
npx -y @jasontanswe/railway-mcp <RAILWAY_API_TOKEN>Create or edit your Claude for Desktop config file:
macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the railway-mcp server to your configuration with your API token:
"railway": {
"command": "npx",
"args": ["-y", "@jasontanswe/railway-mcp"],
"env": {
"RAILWAY_API_TOKEN": "your-railway-api-token-here"
}
}When you have multiple MCP servers, your config file might look like this:
{
"mcpServers": {
// ... All of your existing MCP servers ...
// Add the railway-mcp server to your configuration with your API token
"railway": {
"command": "npx",
"args": ["-y", "@jasontanswe/railway-mcp"],
"env": {
"RAILWAY_API_TOKEN": "your-railway-api-token-here"
}
}
}
}Restart Claude for Desktop
You can now start using Railway tools directly in Claude. For example:
Please list all my Railway projectsAlternatively, if you don't want to add your token to the configuration file, you can configure it within Claude using:
Please configure the Railway API with my token: {YOUR_API_TOKEN_HERE}This server best combines with MCP-clients that have access to terminal or with Git (Cursor, Windsurf). Using this MCP with others is recommended as railway-mcp orchestrates containers and streamlines your deployment process seamlessly.
Git || Official Link
Out of the box, Claude does not have terminal access, so it cannot trigger deployments as it will not be able to get the latest commit.
Spinning up different services and monitoring them are the best use case with Claude.
Use with GitHub MCP or have the repository already setup on GitHub and cloned locally on your machine to leverage full integration with railway-mcp.
When Cursor makes a change, it may forget to push it's changes to GitHub causing it to try and deploy a commit that Railway cannot pull.
SOLUTION: Always ask or include somewhere in your prompt: Have you pushed our changes to GitHub yet?
Railway API tokens provide full access to your account. Keep them secure.
When using the environment variable method, your token is stored in the Claude Desktop configuration file.
Sensitive variable values are automatically masked when displayed.
All API calls use HTTPS for secure communication.
The server's memory-only token storage means your token is never written to disk outside of the configuration file.
If you encounter issues:
Token Authentication Issues
Ensure your API token is valid and has the necessary permissions
If using the environment variable method, check that the token is correctly formatted in the config file
Try using the configure tool directly in Claude if the environment token isn't working
Server Connection Issues
Check that you've installed the latest version of the server
Verify that Node.js version 18 or higher is installed
Restart Claude for Desktop after making changes to the configuration
API Errors
Verify that you're using correct project, environment, and service IDs
Check Railway's status page for any service disruptions
Railway API has rate limits - avoid making too many requests in a short period
We welcome contributions from the community! Please see our Contributing Guidelines for details on how to get started, development guidelines, and debugging information.
configure - Set your Railway API token (only needed if not provided in environment variables)
project-list - List all projects in your account
project-info - Get detailed information about a specific project
project-create - Create a new project with optional team ID
project-delete - Delete a project
project-environments - List all environments in a project
service-list - List all services in a specific project
service-info - Get detailed information about a specific service
service-create-from-repo - Create a new service from a GitHub repository
service-create-from-image - Create a new service from a Docker image
service-delete - Delete a service from a project
service-restart - Restart a service in a specific environment
service-update - Update service configuration (build command, start command, etc.) | š§ Needs Testing
deployment-list - List recent deployments for a service
deployment-trigger - Trigger a new deployment for a service
deployment-logs - Get logs for a specific deployment
deployment-health-check - Check the health/status of a deployment
variable-list - List variables for a service or environment
variable-set - Create or update a variable
variable-delete - Delete a variable
variable-bulk-set - Bulk update variables for a service | š§ Needs Testing
variable-copy - Copy variables between environments | š§ Needs Testing
database-list-types - List all available database types that can be deployed
database-deploy - Deploy a new database service
List projects to get the project ID
Create a new service from a template
Add environment variables
View the service deployment
List projects to find your project ID
List variables to see what's currently set
Create or update variables as needed
Delete any obsolete variables
[UTILITY] Configure the Railway API token for authentication (only needed if not set in environment variables)
ā”ļø Best for: ā Initial setup ā Token updates ā Authentication configuration
ā ļø Not for: Ć Project configuration Ć Service settings Ć Environment variables
ā Next steps: project_list, service_list
ā Related: project_create
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Railway API token (create one at https://railway.app/account/tokens) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool configures a token for authentication but does not disclose side effects (e.g., overwriting existing token, persistence, validation). For a simple setter, the purpose is clear but behavioral details are missing, making it adequate but not comprehensive.
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 emojis, checkmarks, and cross marks to denote best uses and exclusions. It is front-loaded with the purpose and includes next steps and related tools. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description is fairly complete. It covers purpose, usage scenarios, and exclusions. However, it lacks details on response or error handling, but for a configuration tool, the level of detail is appropriate. Slightly more could be said about behavioral side 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 already describes the token parameter with a URL to create one. The description adds value by noting it is only needed if not set in environment variables, which provides context beyond the schema. With 100% schema coverage, the description enhances usability.
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 configures the Railway API token for authentication, and distinguishes it from project, service, and environment variable configuration. It uses specific verbs and resources, and the 'Best for' and 'Not for' sections further clarify its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says it is only needed if the token is not set in environment variables, and provides best-use cases (initial setup, token updates, authentication configuration) and exclusions (project configuration, service settings, environment variables). It also suggests next steps and related tools, giving clear guidance on when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[QUERY] List all available database types that can be deployed using Railway's official templates
ā”ļø Best for: ā Discovering supported database types ā Planning database deployments ā Checking template availability
ā ļø Not for: Ć Listing existing databases Ć Getting database connection details
ā Alternatives: service_create_from_image
ā Next steps: database_deploy
ā Related: database_deploy, service_create_from_image
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description accurately states that the tool queries and lists database types, which is a read-only operation. It does not mention any side effects or restrictions beyond the scope. Since no annotations are provided, the description carries the full burden and meets it well, though it could add info about potential pagination or caching.
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 well-structured with clear sections, bullet points, and emojis, making it visually scannable. Every sentence serves a purpose: stating the query, listing best uses, exclusions, and next steps. No superfluous 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?
Given the tool has no parameters, no output schema, and is a simple listing operation, the description provides complete context. It explains what the tool does, when to use it, and how it relates to other tools, enabling an AI agent to correctly select and invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description correctly implies no parameters are needed. Schema description coverage is 100% (vacuous), and the description adds context about what the query returns, which is sufficient for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource, 'List all available database types,' clearly indicating the tool's function. It distinguishes itself from sibling tools by explicitly stating its scope (official templates) and contrasting with related tools in the 'Not for' section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to use ('Best for'), when not to use ('Not for'), and provides alternatives ('Alternative: service_create_from_image') and next steps ('Next steps: database_deploy'), giving clear guidance on selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] List recent deployments for a service in a specific environment
ā”ļø Best for: ā Viewing deployment history ā Monitoring service updates
ā Prerequisites: service_list
ā Next steps: deployment_logs, deployment_trigger
ā Related: service_info, service_restart
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Optional: Maximum number of deployments to return (default: 10) | |
| projectId | Yes | ID of the project containing the service | |
| serviceId | Yes | ID of the service to list deployments for | |
| environmentId | Yes | ID of the environment to list deployments from (usually obtained from service_list) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose ordering, pagination, or default limit behavior beyond 'recent deployments'. For a list tool with a limit parameter, additional behavioral context would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with structured sections (Best for, Prerequisites, Next steps, Related). Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters and no output schema, the description covers prerequisites, related tools, and usage context well. It does not describe the response format, but that is acceptable 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?
Schema coverage is 100%, so baseline is 3. Description adds minimal extra meaning, only noting that environmentId is 'usually obtained from service_list'. No further parameter elaboration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'list recent deployments for a service in a specific environment' with specific verb and resource. The tool is distinct from siblings like deployment_logs, deployment_status, and deployment_trigger.
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?
Includes explicit 'Best for' usage scenarios, prerequisites (service_list), next steps (deployment_logs, deployment_trigger), and related tools, providing clear guidance on when and how to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Get logs for a specific deployment
ā”ļø Best for: ā Debugging deployment issues ā Monitoring deployment progress ā Checking build output
ā ļø Not for: Ć Service runtime logs Ć Database logs
ā Prerequisites: deployment_list
ā Next steps: deployment_status
ā Related: service_info, deployment_trigger
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of log entries to fetch | |
| deploymentId | Yes | ID of the deployment to get logs for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It does not disclose behavioral traits like rate limits, pagination, or authentication requirements. For a simple log retrieval, basic transparency is sufficient but could be improved by noting that logs are for deployment builds, not runtime.
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?
Well-structured with bullet points for best uses, not-for, prerequisites, next steps, and related tools. Every sentence adds value, and it is very concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could explain the content or format of logs, but it does not. However, it provides context about usage and related tools, and the tool is simple. Almost complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (deploymentId and limit). The description does not add further meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get logs for a specific deployment' with a specific verb and resource. It distinguishes from siblings like service_info (runtime logs) and deployment_trigger (triggering deployment).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists use cases (debugging, monitoring, checking build output) and non-use cases (service runtime logs, database logs). Also mentions prerequisite (deployment_list) and next step (deployment_status), providing clear context for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Check the current status of a deployment
ā”ļø Best for: ā Monitoring deployment progress ā Verifying successful deployments ā Checking for deployment failures
ā ļø Not for: Ć Service runtime logs Ć Database logs
ā Prerequisites: deployment_list, deployment_trigger
ā Next steps: deployment_logs
ā Related: service_info, service_restart, deployment_wait
| Name | Required | Description | Default |
|---|---|---|---|
| deploymentId | Yes | ID of the deployment to check status for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose behavioral traits beyond the obvious status check, such as read-only nature or potential side effects. While adequate for a simple query, it could explicitly state that it does not modify state.
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 highly concise with a well-organized structure using bullet points and symbols. It front-loads the purpose and efficiently uses sections, making it easy for an AI 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?
Given the low complexity (one parameter, no output schema), the description is complete. It covers prerequisites, next steps, and related tools, and provides usage categories. No gaps identified for 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 coverage is 100% for the single parameter (deploymentId), which has a clear description. The tool description does not add additional meaning beyond the schema, so 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 'Check the current status of a deployment' and lists specific use cases like monitoring progress and verifying successes, distinguishing it from sibling tools such as deployment_logs and service_info.
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 'Best for' and 'Not for' sections, plus lists prerequisites (deployment_list, deployment_trigger) and next steps (deployment_logs), giving comprehensive guidance on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Trigger a new deployment for a service
ā”ļø Best for: ā Deploying code changes ā Applying configuration updates ā Rolling back to previous states
ā ļø Not for: Ć Restarting services (use service_restart) Ć Updating service config (use service_update) Ć Database changes
ā Prerequisites: service_list
ā Alternatives: service_restart
ā Next steps: deployment_logs, deployment_status
ā Related: variable_set, service_update
| Name | Required | Description | Default |
|---|---|---|---|
| commitSha | Yes | Specific commit SHA from the Git repository | |
| projectId | Yes | ID of the project | |
| serviceId | Yes | ID of the service | |
| environmentId | Yes | ID of the environment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'API' but does not disclose behavioral traits like idempotency, rate limits, or whether the deployment is synchronous. It does note prerequisites, but lacks depth on what happens on trigger.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is extremely concise and well-structured using bullet points, emojis, and clear section headers. Every sentence adds value, making it easy for an AI agent 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?
Given no output schema and no annotations, the description provides substantial context: purpose, usage, alternatives, prerequisites, next steps. However, it lacks details on return values or potential side effects, leaving minor gaps in completeness for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description does not add additional meaning beyond the schema's parameter descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action 'Trigger a new deployment for a service' and lists specific use cases (deploying code, config updates, rollbacks). It distinguishes from siblings by explicitly stating what it is not for, e.g., 'Restarting services (use service_restart)'.
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 'Best for' and 'Not for' sections with alternative tool names. Also includes prerequisites ('service_list') and next steps ('deployment_logs, deployment_status'), giving clear guidance on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Check if a domain is available for use
ā”ļø Best for: ā Validating domain availability ā Pre-deployment checks ā Domain planning
ā Next steps: domain_create
ā Related: domain_list
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Domain name to check availability for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description labels it as an '[API]' call, implying a network operation, but doesn't detail side effects or authentication requirements. However, for a simple check tool, this is sufficient. Without annotations, it carries the burden but still scores high as no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences plus bullet points. Front-loaded with '[API]'. Every sentence is useful and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required param, no output schema, no annotations), the description fully covers its purpose, use cases, and related tools. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (the 'domain' parameter is described). The description reinforces the parameter's purpose but adds minimal additional meaning beyond 'Domain name to check availability for'. Baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Check if a domain is available for use' with a specific verb and resource. The 'Best for' section further clarifies its purpose and distinguishes it from siblings like domain_create and domain_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?
Provides explicit guidance on when to use ('Validating domain availability, Pre-deployment checks, Domain planning') and what to do next ('Next steps: domain_create'). Also lists a related tool (domain_list), giving clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Create a new domain for a service
ā”ļø Best for: ā Setting up custom domains ā Configuring service endpoints ā Adding HTTPS endpoints
ā ļø Not for: Ć TCP proxy setup (use tcp_proxy_create) Ć Internal service communication
ā Prerequisites: service_list, domain_check
ā Alternatives: tcp_proxy_create
ā Next steps: domain_update
ā Related: service_info, domain_list
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | Custom domain name (optional, as railway will generate one for you and is generally better to leave it up to railway to generate one. There's usually no need to specify this and there are no use cases for overriding it.) | |
| suffix | No | Suffix for the domain (optional, railway will generate one for you and is generally better to leave it up to railway to generate one.) | |
| serviceId | Yes | ID of the service | |
| targetPort | No | Target port for the domain (optional, as railway will use the default port for the service and detect it automatically.) | |
| environmentId | Yes | ID of the environment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must stand alone. It only states 'Create a new domain' without disclosing side effects, authorization requirements, idempotency, or limits. For a creation tool, this is insufficient 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?
Description is well-structured with bullet points and clear sections (Best for, Not for, Prerequisites, etc.). It is concise but informative. Minor noise from '[API]' prefix and emojis, but overall 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?
While the description includes prerequisites and next steps, it lacks context about the return value or success behavior (no output schema). For a tool with 5 parameters and no annotations, more detail about expected results or side effects 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 coverage is 100%, so the description does not need to repeat parameter details. The description adds no extra meaning beyond what schema already provides; thus, baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create a new domain for a service' with specific use cases (custom domains, service endpoints, HTTPS). Distinguishes from siblings like tcp_proxy_create by explicitly listing 'Not for' items.
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 best-for/not-for sections, prerequisites (service_list, domain_check), alternatives (tcp_proxy_create), and next steps (domain_update). Guides when to use and when not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Delete a domain from a service
ā”ļø Best for: ā Removing unused domains ā Cleaning up configurations ā Domain management
ā ļø Not for: Ć Temporary domain disabling Ć Port updates (use domain_update)
ā Prerequisites: domain_list
ā Alternatives: domain_update
ā Related: service_update
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ID of the domain to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states 'delete' which implies destructiveness but provides no details on irreversibility, authorization, rate limits, or side effects. The description adds minimal behavioral context beyond the tool 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 highly concise, uses structured sections with emojis and bullet points for clarity, and front-loads the core action. Every sentence and symbol adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and no output schema, the description covers the essentials: purpose, usage scenarios, alternatives, and prerequisites. It does not explain return values, but that is acceptable given the action's triviality.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the 'id' parameter as 'ID of the domain to delete'. The description does not add any additional meaning or constraints beyond that baseline, so it merits a standard score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Delete a domain from a service' and lists specific best use cases like removing unused domains and cleaning up configurations. It distinguishes from sibling tools by noting it is not for temporary disabling or port updates, which are covered by domain_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use and when-not-to-use guidelines, mentions prerequisites (domain_list), alternatives (domain_update), and related tools (service_update). This fully informs the agent about context and selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] List all domains (both service and custom) for a service
ā”ļø Best for: ā Viewing service endpoints ā Managing domain configurations ā Auditing domain settings
ā Prerequisites: service_list
ā Next steps: domain_create, domain_update
ā Related: service_info, tcp_proxy_list
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | ID of the project containing the service | |
| serviceId | Yes | ID of the service to list domains for | |
| environmentId | Yes | ID of the environment that the service is in to list domains from (usually obtained from service_list) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Implies read-only via 'Viewing' but does not explicitly state auth, rate limits, or side effects. For a list tool, this is adequate but not thorough.
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?
Fairly concise with bullet points and emojis for organization. Front-loaded purpose. Could trim '[API]' but overall 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?
No output schema exists, and description does not explain return format or fields. Missing info on pagination/filtering. Incomplete for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, so baseline 3. Description adds no additional parameter details beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List all domains (both service and custom) for a service', specifying verb and resource. Distinguishes from siblings like domain_create, domain_check. Best-for section adds clarity.
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 prerequisites (service_list), next steps (domain_create, domain_update), and related tools, giving workflow context. Does not explicitly exclude alternatives but offers good guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Update a domain's configuration
ā”ļø Best for: ā Changing target ports ā Updating domain settings ā Reconfiguring endpoints
ā ļø Not for: Ć Changing domain names (delete and recreate instead) Ć TCP proxy configuration
ā Prerequisites: domain_list
ā Next steps: domain_list
ā Related: service_update
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ID of the domain to update | |
| targetPort | Yes | New port number to route traffic to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears full burden but only states it updates configuration. It does not disclose side effects, reversibility, or potential impacts like downtime or deployment triggers, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured with emojis and bullet points, front-loading the purpose. Every sentence serves a distinct role (purpose, best-for, not-for, prerequisites, next steps, related) 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 update tool with two required parameters and no output schema, the description covers the core use case, prerequisites, and next steps. It lacks details on return values or effect confirmation but is adequate given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both id and targetPort. The description adds minimal extra meaning beyond restating that targetPort is for routing traffic from the best-for list, so it does not significantly enhance 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 'Update a domain's configuration' with specific actions like changing target ports, updating settings, and reconfiguring endpoints. It effectively distinguishes from sibling tools like domain_create, domain_delete, and service_update through its 'Not for' section and related tool mention.
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 'Not for' section explicitly excludes changing domain names (recommending delete/recreate) and TCP proxy configuration, providing clear alternatives. Prerequisites and next steps (domain_list) give flow guidance, though a broader comparison with all siblings is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] List all environment variables for a service
ā”ļø Best for: ā Viewing service configuration ā Auditing environment variables ā Checking connection strings
ā Prerequisites: service_list
ā Next steps: variable_set, variable_delete
ā Related: service_info, variable_bulk_set
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | ID of the project containing the service | |
| serviceId | No | Optional: ID of the service to list variables for, if not provided, shared variables across all services will be listed | |
| environmentId | Yes | ID of the environment to list variables from (usually obtained from service_list) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should explicitly mention read-only behavior and response format. The word 'List' implies no side effects, but it does not explicitly state safety or absence of destructive actions. It also omits details about pagination, rate limits, or auth requirements. While it adds value with prerequisites and next steps, behavioral transparency is only moderate.
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 very concise, uses structured bullet points with clear sections (Best for, Prerequisites, Next steps, Related), and front-loads the key action. Every sentence serves a purpose, and there is no 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 no annotations and no output schema, the description could provide more complete context. It does not describe the response format (e.g., array of variable objects), potential for large response, or any pagination behavior. It covers prerequisites and related tools well but leaves gaps in operational 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?
Input schema coverage is 100%, so the baseline is 3. The description does not elaborate on parameters beyond what the schema already provides (e.g., the meaning of optional serviceId). No additional semantics are added, so the score remains at the baseline.
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 'List all environment variables for a service', providing a specific verb and resource. The 'Best for' bullet points further refine use cases (viewing config, auditing, checking connection strings), and the related tools clearly distinguish it from siblings like variable_set and variable_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes prerequisites ('service_list'), next steps ('variable_set, variable_delete'), and related tools, offering a clear usage flow. However, it lacks explicit guidance on when not to use this tool (e.g., if you need to filter variables by name), which would enhance the guidelines. Still, the provided context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Create a new Railway project
ā”ļø Best for: ā Starting new applications ā Setting up development environments ā Creating project spaces
ā ļø Not for: Ć Duplicating existing projects
ā Next steps: service_create_from_repo, service_create_from_image, database_deploy
ā Related: project_delete, project_update
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for the new project | |
| teamId | No | Optional team ID to create the project under |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It only states creation but omits details on permissions, idempotency, error behavior (e.g., duplicate name handling), or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with emojis and bullets, but includes some redundancy (e.g., both 'Next steps' and 'Related' sections could be merged). Still efficient overall.
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?
Provides use case context via 'Best for' but lacks explanation of return values or side effects. With no output schema and no annotations, more detail is needed for full 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?
Input schema has 100% description coverage, so baseline is 3. The description adds no additional meaning beyond the schema (e.g., name format, teamId 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 clearly states the action (create) and resource (project), and distinguishes from siblings like project_delete and project_update. The 'Best for' bullets further clarify its 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?
Explicit 'Best for' and 'Not for' sections provide clear guidance on when to use the tool, and next steps suggest related tools for subsequent actions, offering comprehensive usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Delete a Railway project and all its resources
ā”ļø Best for: ā Removing unused projects ā Cleaning up test projects
ā ļø Not for: Ć Temporary project deactivation Ć Service-level cleanup (use service_delete)
ā Prerequisites: project_list, project_info
ā Alternatives: service_delete
ā Related: project_create
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | ID of the project to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description indicates destructiveness by stating it deletes the project and all resources. It clarifies permanent deletion by noting 'not for temporary deactivation.' However, it does not explicitly state irreversibility or potential consequences like cascading deletions.
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, uses clear section headers and bullet points with emojis, and every sentence adds value. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive tool with one parameter and no output schema, the description covers purpose, usage context, alternatives, and prerequisites comprehensively. Could mention irreversibility explicitly, but overall it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter (projectId) already described. The description adds no additional parameter detail but provides context by listing prerequisites and related tools, helping the agent understand how to obtain the projectId.
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 a Railway project and all its resources') with specific verb and resource. It distinguishes from sibling tools by noting exclusions (temporary deactivation, service-level cleanup).
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 best-for cases (removing unused, cleaning up test), not-for cases (temporary deactivation, service-level cleanup), alternative tool (service_delete), and prerequisites (project_list, project_info).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all environments in a project
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | ID of the project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description provides no behavioral traits: not stating it is read-only (though likely), no mention of permissions, rate limits, or side effects. Annotations are missing entirely, placing full burden on description, which fails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is extremely concise (one sentence) with no wasteful words. However, it may be too brief for a tool with no output schema or annotations, slightly reducing score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 param, no output schema, no annotations), description should provide richer context like expected return format, pagination, or filters. It lacks any such detail, making it 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 coverage is 100% as the sole parameter 'projectId' is described as 'ID of the project'. Description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('List') and resource ('environments') with scope ('in a project'), using a specific verb and noun. It distinguishes from sibling tools like project_list or deployment_list, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites or exclusions. The agent is left to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Get detailed information about a specific Railway project
ā”ļø Best for: ā Viewing project details and status ā Checking environments and services ā Project configuration review
ā Prerequisites: project_list
ā Next steps: service_list, variable_list
ā Related: project_update, project_delete
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | ID of the project to get information about |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. The word 'get' and the listed best uses (all read operations) strongly imply a non-destructive, read-only operation. However, it does not explicitly state 'read-only' or mention potential pitfalls like authentication or missing project, but for a simple get tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line purpose followed by bullet points for best uses, prerequisites, next steps, and related tools. Every sentence provides value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter and no output schema, the description covers purpose, usage context, dependencies, and related tools. It gives a good sense of what is returned ('detailed information', 'environments and services', 'project configuration review'). Could be more explicit about error conditions, but overall sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any extra meaning for the parameter beyond what the schema provides. It mentions project_list as a prerequisite, which indirectly helps but is not parameter-specific.
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 'Get detailed information about a specific Railway project' with a strong verb and resource. It lists specific best uses (viewing project details, checking environments/services, project configuration review) that distinguish it from sibling tools like project_update or project_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists prerequisites (project_list), next steps (service_list, variable_list), and related tools (project_update, project_delete). This provides clear when-to-use and when-not-to-use guidance, fully meeting the dimension criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] List all projects in your Railway account
ā”ļø Best for: ā Getting an overview of all projects ā Finding project IDs ā Project discovery and management
ā Next steps: project_info, service_list
ā Related: project_create, project_delete
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description implies read-only list operation. For a simple tool with no parameters, it is transparent enough, though it doesn't mention potential limitations like pagination (likely not applicable).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence for purpose, bullet list for usage, arrows for related tools. Front-loaded with key information, no superfluous content.
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?
Fully adequate for a simple list tool with no parameters or output schema. Covers purpose, usage context, and next steps. No missing elements given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, so schema coverage is effectively 100%. Description correctly adds no parameter info as none exist, meeting the baseline expectation for no-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List all projects in your Railway account', specifying the verb (list) and resource (projects). Provides 'Best for' bullets explicitly distinguishing use cases from siblings like project_info and project_create/delete.
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?
Includes explicit 'Best for' context (overview, finding IDs, discovery) and next steps (project_info, service_list) and related tools (project_create, project_delete), guiding when to use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Create a new service from a Docker image
ā”ļø Best for: ā Custom database deployments ā Pre-built container deployments ā Specific version requirements
ā ļø Not for: Ć Standard database deployments (use database_deploy) Ć GitHub repository deployments (use service_create_from_repo) Ć Services needing build process
ā Prerequisites: project_list
ā Alternatives: database_deploy, service_create_from_repo
ā Next steps: variable_set, service_update, tcp_proxy_create
ā Related: volume_create, deployment_trigger
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional custom name for the service | |
| image | Yes | Docker image to use (e.g., 'postgres:13-alpine') | |
| projectId | Yes | ID of the project to create the service in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits like authorization needs, side effects, or cancellation behavior. It only states it creates a service, omitting important details such as idempotency, required permissions, or implications of image availability.
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?
Well-structured with emojis, bullet points, and clear sections. Every sentence adds value; no fluff. 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?
Covers purpose, usage guidelines, prerequisites, and next steps. However, lacks return value description (no output schema) and behavioral details, which are needed given no 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?
Input schema has 100% description coverage, so baseline is 3. The description adds no extra parameter meaning beyond the schema; it repeats 'Docker image' but does not clarify format or validation rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new service from a Docker image' and distinguishes from siblings by listing excluded use cases and alternative tools (database_deploy, service_create_from_repo).
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 'Best for' and 'Not for' sections, lists prerequisites (project_list), alternatives, next steps, and related tools, giving comprehensive when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Create a new service from a GitHub repository
ā”ļø Best for: ā Deploying applications from source code ā Services that need build processes ā GitHub-hosted projects
ā ļø Not for: Ć Pre-built Docker images (use service_create_from_image) Ć Database deployments (use database_deploy) Ć Static file hosting
ā Prerequisites: project_list
ā Alternatives: service_create_from_image, database_deploy
ā Next steps: variable_set, service_update
ā Related: deployment_trigger, service_info
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional custom name for the service | |
| repo | Yes | GitHub repository URL or name (e.g., 'owner/repo') | |
| projectId | Yes | ID of the project to create the service in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description mentions it's an API call and requires prerequisite project_list, but doesn't detail potential side effects (e.g., costs, permissions, rebuild times). No annotations provided to compensate.
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?
Well-structured with sections, emojis, and arrows for clarity. Some redundancy in arrows, but overall efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers prerequisites, alternatives, and next steps. Missing output schema and error handling, but for a creation tool it's fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description adds no extra parameter-level detail beyond what schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new service from a GitHub repository', specifying the action (create), resource (service), and source (GitHub repo). It distinguishes from siblings like service_create_from_image and database_deploy.
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?
Explicit sections for 'Best for', 'Not for', prerequisites, alternatives, next steps, and related tools provide comprehensive guidance on when to use and avoid this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Delete a service from a project
ā”ļø Best for: ā Removing unused services ā Cleaning up test services ā Project reorganization
ā ļø Not for: Ć Temporary service stoppage (use service_restart) Ć Updating service configuration (use service_update)
ā Prerequisites: service_list, service_info
ā Alternatives: service_restart
ā Related: project_delete
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | ID of the project containing the service | |
| serviceId | Yes | ID of the service to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly indicates destruction via 'Delete', which implies irreversibility. However, it lacks details on cascading effects or safety concerns. The prerequisites hint at required prior steps, but could be more explicit about the destructive nature. Still above average for 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?
Extremely concise and well-structured with emojis and clear sections (Best for, Not for, Prerequisites, Alternatives, Related). Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of a delete operation and no output schema, the description covers purpose, usage guidelines, and prerequisites. It could optionally mention return value or confirmation, but overall it is sufficiently complete 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 coverage is 100%, so the schema already documents both parameters (projectId, serviceId). Description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Delete a service') and resource ('from a project'). It distinguishes from siblings by listing what it's best for (removing unused services, test cleanup) and what it's not for (temporary stoppage, updating config), making it 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?
Provides clear when-to-use (removing unused services, test cleanup, project reorganization) and when-not-to-use (temporary stoppage, updating config). Lists prerequisites and an alternative (service_restart), giving the agent explicit decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Get detailed information about a specific service
ā”ļø Best for: ā Viewing service configuration and status ā Checking deployment details ā Monitoring service health
ā Prerequisites: service_list
ā Next steps: deployment_list, variable_list
ā Related: service_update, deployment_trigger
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | ID of the project containing the service | |
| serviceId | Yes | ID of the service to get information about | |
| environmentId | Yes | ID of the environment to check (usually obtained from service_list) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly indicates a read-only operation ('Get detailed information'), which is transparent about non-mutative behavior. It could additionally mention idempotency or lack of side effects, but the current description is sufficient for a read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear heading followed by bullet points for 'Best for', 'Prerequisites', 'Next steps', and 'Related'. Every sentence adds value, and the format is 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?
Given the absence of output schema and annotations, the description provides a fairly complete picture: it lists the kinds of information returned (configuration, status, deployment details, health) and includes usage context with prerequisites and next steps. It lacks mention of error conditions or authorization, but for a simple read tool, it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so the baseline is 3. The description adds minor value by hinting that environmentId is typically obtained from service_list, but does not provide additional detail beyond the schema. Thus, a 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 tool retrieves detailed information about a specific service, with explicit use cases like viewing configuration, status, deployment details, and health monitoring. This distinguishes it from sibling tools like service_list (listing) and service_update (mutation).
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?
Excellent guidance: mentions 'Prerequisites: service_list', 'Next steps: deployment_list, variable_list', and 'Related: service_update, deployment_trigger'. This tells the agent when to use this tool and suggests relevant alternatives, making the usage context very clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] List all services in a specific Railway project
ā”ļø Best for: ā Getting an overview of a project's services ā Finding service IDs ā Checking service status
ā Prerequisites: project_list
ā Next steps: service_info, deployment_list
ā Related: project_info, variable_list
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | ID of the project to list services from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description must carry transparency. The description implies a read-only list operation, but lacks disclosure on authentication, scoping, or potential pagination. Adequate for a simple list but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise and well-structured with bullet points and emojis for readability. However, the emojis are not strictly necessary and add slight noise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description does not explain return values, error conditions, or pagination (if any). For a list tool, this is a gap, but the prerequisites and next steps partially compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers projectId with built-in description. The description echoes the schema's meaning without adding new semantic details, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List all services in a specific Railway project' with a specific verb and resource, distinguishing it from siblings like service_info (single service) and service_create (creation).
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 best-for use cases, prerequisites, next steps, and related tools, helping agents decide when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Restart a service in a specific environment
ā”ļø Best for: ā Applying configuration changes ā Clearing service state ā Resolving runtime issues
ā ļø Not for: Ć Deploying new code (use deployment_trigger) Ć Updating service config (use service_update) Ć Long-term service stoppage (use service_delete)
ā Prerequisites: service_list
ā Alternatives: deployment_trigger
ā Related: service_info, deployment_logs
| Name | Required | Description | Default |
|---|---|---|---|
| serviceId | Yes | ID of the service to restart | |
| environmentId | Yes | ID of the environment where the service should be restarted (usually obtained from service_info) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions 'Restart' which implies a state change but does not specify whether it's destructive, required permissions, impact on connected clients, or rollback capabilities. It only describes high-level purpose without behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured using emojis and clear sections (Best for, Not for, Prerequisites, Alternatives, Related). Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple restart tool with two parameters and no output schema, the description covers purpose, usage guidelines, and context well. It could benefit from behavioral details like idempotency or side effects, but given the tool's simplicity, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description adds no additional meaning beyond the schema for these parameters. Baseline 3 is appropriate as the schema already documents them adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool restarts a service in a specific environment. It distinguishes from siblings by providing explicit use cases and exclusions (e.g., not for deploying new code, use deployment_trigger instead).
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 explicit when-to-use (applying config changes, clearing state, resolving runtime issues) and when-not-to-use (deploying code, updating config, long-term stoppage). It also lists prerequisites (service_list), alternatives (deployment_trigger), and related tools (service_info, deployment_logs).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Update a service's configuration
ā”ļø Best for: ā Changing service settings ā Updating resource limits ā Modifying deployment configuration
ā ļø Not for: Ć Updating environment variables (use variable_set) Ć Restarting services (use service_restart) Ć Triggering new deployments (use deployment_trigger)
ā Prerequisites: service_list, service_info
ā Next steps: deployment_trigger
ā Related: service_restart, variable_set
| Name | Required | Description | Default |
|---|---|---|---|
| region | No | Optional: Region to deploy the service in | |
| projectId | Yes | ID of the project containing the service | |
| serviceId | Yes | ID of the service to update | |
| numReplicas | No | Optional: Number of service replicas to run | |
| buildCommand | No | Optional: Command to build the service | |
| startCommand | No | Optional: Command to start the service | |
| environmentId | Yes | ID of the environment to update (usually obtained from service_info) | |
| rootDirectory | No | Optional: Root directory containing the service code | |
| healthcheckPath | No | Optional: Path for health checks | |
| sleepApplication | No | Optional: Whether to enable sleep mode |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It does not detail behavioral traits such as whether the operation is destructive, what permissions are needed, or side effects (e.g., does it trigger a restart?). It only implies mutation, but lacks specifics beyond 'update'.
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?
Concise and well-structured: uses emojis, bullet points, clear sections, and front-loads the purpose. Every sentence adds value, and there is no unnecessary 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 fairly complete given the 10 parameters (3 required) and no output schema. It includes prerequisites, next steps, and related tools. However, it does not cover return values or potential error conditions, which slightly reduces 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 input schema has 100% description coverage, so the schema already explains each parameter. The description adds no additional meaning per parameter beyond listing categories (e.g., 'resource limits'), which is already implied. Given the high coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a service's configuration' and lists specific use cases like changing settings, updating resource limits, and modifying deployment configuration. This distinguishes it well from siblings like service_restart and variable_set.
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?
Excellent guidelines: 'Best for' and 'Not for' sections explicitly list when to use and when not to, with alternatives (e.g., variable_set, service_restart, deployment_trigger). Also includes prerequisites and next steps, providing clear context for the AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Create a new TCP proxy for a service
ā”ļø Best for: ā Setting up database access ā Configuring external connections ā Exposing TCP services
ā ļø Not for: Ć HTTP/HTTPS endpoints (use domain_create) Ć Internal service communication
ā Prerequisites: service_list
ā Alternatives: domain_create
ā Next steps: tcp_proxy_list
ā Related: service_info, service_update
| Name | Required | Description | Default |
|---|---|---|---|
| serviceId | Yes | ID of the service | |
| environmentId | Yes | ID of the environment (usually obtained from service_info) | |
| applicationPort | Yes | Port of application/service to proxy, usually based off of the service's Dockerfile or designated running port. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not contradict the lack of annotations (none provided). It clearly indicates that creation is for TCP proxies, which is a non-destructive mutation. However, it does not detail what happens upon success (e.g., returns a proxy ID) or any potential side effects. Still, the behavioral intent is well-communicated, earning a 4.
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, structured with headings and bullet points using emojis. Every sentence provides value without redundancy. It front-loads the purpose and then organizes additional guidance logically.
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 (3 params, no output schema), the description covers purpose, usage guidelines, and prerequisites well. The missing explanation of the return value or outcome is a minor gap, but the context is largely complete for a creation 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?
Input schema has 100% coverage with a baseline of 3. The description adds minimal extra meaning beyond the schema: it mentions that environmentId is 'usually obtained from service_info'. This is helpful but not substantial. The parameters are already well-documented 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 description clearly states 'Create a new TCP proxy for a service' with specific use cases (database access, external connections, TCP services) and explicitly distinguishes from HTTP/HTTPS endpoints (domain_create) and internal service communication. It provides a clear verb-resource definition and differentiates from sibling tools like domain_create and tcp_proxy_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?
The description includes explicit 'Best for' and 'Not for' categories, prerequisites (service_list), alternatives (domain_create), next steps (tcp_proxy_list), and related tools. This provides comprehensive guidance on when and how to use this tool, including what to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Delete a TCP proxy
ā”ļø Best for: ā Removing unused proxies ā Security management ā Endpoint cleanup
ā ļø Not for: Ć Temporary proxy disabling Ć Port updates
ā Prerequisites: tcp_proxy_list
ā Related: service_update
| Name | Required | Description | Default |
|---|---|---|---|
| proxyId | Yes | ID of the TCP proxy to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Indicates permanent deletion via 'Not for: Temporary proxy disabling', but lacks details on reversibility, cascading effects, or confirmation. Still sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with bullet points and emojis, front-loads purpose, and uses clear sections. 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?
Given one required parameter, no output schema, and straightforward behavior, the description covers key aspects: purpose, usage guidelines, prerequisites, and related tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and already describes proxyId as 'ID of the TCP proxy to delete'. Description adds no extra semantics beyond that. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Delete a TCP proxy' with specific verb and resource. Best for section reinforces purpose and distinguishes from siblings like tcp_proxy_create and tcp_proxy_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?
Explicitly lists when to use (Removing unused proxies, Security management, Endpoint cleanup) and when not (Temporary proxy disabling, Port updates). Also mentions prerequisites (tcp_proxy_list) and related tool (service_update).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] List all TCP proxies for a service in a specific environment
ā”ļø Best for: ā Viewing TCP proxy configurations ā Managing external access ā Auditing service endpoints
ā Prerequisites: service_list
ā Next steps: tcp_proxy_create
ā Related: domain_list, service_info
| Name | Required | Description | Default |
|---|---|---|---|
| serviceId | Yes | ID of the service to list TCP proxies for | |
| environmentId | Yes | ID of the environment containing the service |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description is the sole source of behavioral info. It only states that it lists TCP proxies without mentioning any constraints, side effects, pagination, or authentication requirements. The behavioral trait is minimally implied as read-only, but no details are given.
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, starting with a clear one-liner, followed by well-structured bullet points for best uses, prerequisites, next steps, and related tools. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two required parameters and no output schema, the description provides adequate context: purpose, use cases, prerequisites, and follow-up actions. It lacks behavioral details but is otherwise 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?
Input schema has 100% coverage with descriptions for both parameters. The description does not add additional parameter meaning beyond the schema, but it does imply that serviceId comes from a prior service_list call. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'TCP proxies for a service in a specific environment'. It distinguishes itself from siblings like tcp_proxy_create by focusing on listing, and the 'Best for' section reinforces its use cases.
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 explicit usage context with 'Best for' checkmarks, prerequisites (service_list), next steps (tcp_proxy_create), and related tools (domain_list, service_info). It is only missing explicit when-not conditions, but the guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WORKFLOW] Deploy a new service from a template
ā”ļø Best for: ā Starting new services from templates ā Quick service deployment ā Using pre-configured templates
ā ļø Not for: Ć Custom service configurations Ć GitHub repository deployments (use service_create_from_repo)
ā Prerequisites: template_list
ā Alternatives: service_create_from_repo, service_create_from_image, database_deploy
ā Next steps: service_info, variable_list
ā Related: service_update, deployment_trigger
| Name | Required | Description | Default |
|---|---|---|---|
| teamId | No | ID of the team to create the service in (if not provided, will use the default team) | |
| projectId | Yes | ID of the project to create the service in | |
| templateId | Yes | ID of the template to use | |
| environmentId | Yes | ID of the environment to deploy to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It labels the tool as '[WORKFLOW]' and mentions prerequisites/alternatives, but does not disclose side effects, authorization needs, rate limits, or what gets created/destroyed. Lacks behavioral depth expected for a workflow 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?
Well-structured with bullet points and clear sections, front-loading the main purpose. Slightly verbose due to multiple sections, but every sentence adds value and the structure aids readability.
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?
Provides good contextual clues (prerequisites, alternatives, next steps) but omits details about the return value (e.g., deployment ID or status) and does not explain parameter relationships. Given no output schema, this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive parameter names and descriptions in the schema. The description adds no extra meaning beyond the workflow context, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Deploy a new service from a template' (specific verb+resource) and distinguishes from siblings like service_create_from_repo and database_deploy via explicit 'Not for' and 'Alternatives' sections.
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 'Best for' and 'Not for' sections, prerequisites (template_list), alternatives (service_create_from_repo, etc.), next steps, and related tools, giving comprehensive when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Get the status of a workflow
ā”ļø Best for: ā Checking workflow status
ā ļø Not for: Ć Creating new services
ā Next steps: service_info
ā Related: template_list, template_deploy
| Name | Required | Description | Default |
|---|---|---|---|
| workflowId | Yes | ID of the workflow to get the status of |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose behavioral traits like read-only, authentication needs, or rate limits. The simple 'get' implies a read operation but is not explicit.
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 very concise, using bullet points and emojis for clarity. Every sentence adds value, with no wasted words. However, the best-for section slightly repeats the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, no output schema), the description is adequate for basic usage but could mention possible status values or if there are any side 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?
Schema coverage is 100% with a clear parameter description. The tool description adds no additional parameter information beyond what the schema provides, so score is baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets the status of a workflow, and the best-for section reinforces this. It distinguishes itself from siblings like template_list and template_deploy by focusing on status retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use (checking workflow status) and when not to (creating new services), and provides next steps and related tools, offering clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] List all available templates on Railway
ā”ļø Best for: ā Discovering available templates ā Planning service deployments ā Finding template IDs and sources
ā ļø Not for: Ć Listing existing services Ć Getting service details
ā Alternatives: service_create_from_repo, service_create_from_image
ā Next steps: service_create_from_template
ā Related: database_list_types
| Name | Required | Description | Default |
|---|---|---|---|
| searchQuery | No | Optional search query to filter templates by name and description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
As no annotations are provided, the description must convey behavioral traits. It indicates a read operation ('List all available templates'), which is safe. However, it does not mention if the list is paginated or if there are any rate limits, though the simplicity of the tool reduces the need.
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 with bullet points and icons. However, the use of emojis may not be parsed optimally by all agents. The main action is front-loaded and 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?
For a simple list tool with no output schema, the description covers the key aspects: what it lists and how to use it (optional search). It mentions 'template IDs and sources' in the best-for section, which gives a hint about the return data. Could be more explicit about the return format, but 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?
The input schema covers 100% of parameters with a clear description for 'searchQuery'. The tool description adds no extra meaning beyond 'filter templates by name and description', so it meets the baseline but does not exceed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List all available templates' and provides specific use cases like 'Discovering available templates' and 'Finding template IDs and sources', which precisely identifies the tool's function and distinguishes it 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?
Comprehensive guidelines with 'Best for', 'Not for', alternatives, next steps, and related tools. This gives clear context on when to use this tool versus others, such as 'service_create_from_repo'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WORKFLOW] Create or update multiple environment variables at once
ā”ļø Best for: ā Migrating configuration between services ā Initial service setup ā Bulk configuration updates
ā ļø Not for: Ć Single variable updates (use variable_set) Ć Temporary configuration changes
ā Prerequisites: service_list
ā Alternatives: variable_set
ā Next steps: deployment_trigger, service_restart
ā Related: variable_list, service_update
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | ID of the project containing the service | |
| serviceId | No | Optional: ID of the service for the variables, if omitted updates shared variables) | |
| variables | Yes | Object mapping variable names to values | |
| environmentId | Yes | ID of the environment for the variables (usually obtained from service_list) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. While it states the operation is a bulk create/update, it does not detail important behaviors such as overwrite semantics, validation, limits, side effects (e.g., triggering restarts), or immediacy of changes. This lack of depth is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, emojis, and bullet points that enhance readability. It is slightly lengthy but every part adds value, including workflow hints and related tools. Good balance of detail and conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, bulk operation, no output schema), the description covers use cases, exclusions, alternatives, prerequisites, and next steps. It lacks details on error handling or return behavior, but overall provides sufficient context for an AI agent to use the tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning beyond the schema; it repeats parameter names in context but does not elaborate on formatting, constraints, or usage nuances.
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 or update multiple environment variables at once'), specifies the resource ('environment variables'), and distinguishes it from sibling tools like variable_set by explicitly stating it is not for single variable updates.
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 explicit when-to-use scenarios (migrating configuration, initial setup, bulk updates), when-not-to-use (single variable updates, temporary changes), and names alternatives (variable_set). It also lists prerequisites and next steps, offering comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WORKFLOW] Copy variables from one environment to another
ā”ļø Best for: ā Environment migration ā Configuration sharing ā Environment duplication
ā ļø Not for: Ć Single variable updates (use variable_set) Ć Temporary configuration changes
ā Prerequisites: service_list
ā Alternatives: variable_set
ā Next steps: deployment_trigger, service_restart
ā Related: variable_list, service_update
| Name | Required | Description | Default |
|---|---|---|---|
| overwrite | No | Whether to overwrite existing variables in the target environment | |
| projectId | Yes | ID of the project | |
| serviceId | No | ID of the service (optional, if omitted copies shared variables) | |
| sourceEnvironmentId | Yes | ID of the source environment (usually obtained from project_info) | |
| targetEnvironmentId | Yes | ID of the target environment (usually obtained from project_info) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry burden. It describes the copy operation and overwrite flag but does not explicitly state that it modifies the target environment, potential destructive behavior, or permissions needed. Could be more transparent about mutation and risks.
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?
Well-structured with emojis, bullet points, and clear sections. Front-loaded purpose. Some verbosity due to multiple sections, but overall efficient and 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?
No output schema, so description should cover return value. It does not describe what the tool returns (e.g., success message, count of copied variables). Provides prerequisites and next steps, but misses result explanation for a tool with 5 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 coverage is 100%, baseline 3. The description adds minimal extra meaning beyond schema: source/target environment IDs from project_info, serviceId optional for shared variables, overwrite flag. No further parameter 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 tool copies variables from one environment to another, using specific verbs and resource. It distinguishes from sibling tools like variable_set (single variable updates) and variable_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?
Provides explicit sections: Best for (environment migration, sharing, duplication), Not for (single variable updates, temp changes), Prerequisites (service_list), Alternatives (variable_set), Next steps (deployment_trigger, service_restart), and Related tools. Excellent guidance on when to use and when not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Delete a variable for a service in a specific environment
ā”ļø Best for: ā Removing unused configuration ā Security cleanup ā Configuration management
ā ļø Not for: Ć Temporary variable disabling Ć Bulk variable removal
ā Prerequisites: service_list
ā Next steps: deployment_trigger, service_restart
ā Related: variable_list, variable_set
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the variable to delete | |
| projectId | Yes | ID of the project | |
| serviceId | No | ID of the service (optional, if omitted deletes a shared variable) | |
| environmentId | Yes | ID of the environment to delete the variable from (usually obtained from service_list) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It indicates deletion is permanent but does not detail consequences, irreversibility, permissions, or side effects. The optional serviceId nuance is covered in the schema but not emphasized in the description.
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 with bullet points and emojis. Every line adds value, and there is no unnecessary repetition 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?
While it provides prerequisites and next steps, it lacks information about the return value or confirmation of deletion, and does not explain behavior when deleting shared vs. service-specific variables. For an irreversible action, more detail 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?
Schema coverage is 100%, so the input schema already describes all parameters well. The description does not add additional meaning or context beyond what is in the schema, hence meeting the baseline.
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 deletes a variable for a service in a specific environment. It provides a specific verb and resource, and it distinguishes from related tools by excluding temporary disabling and bulk removal, though it does not explicitly contrast with variable_set or variable_bulk_set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Best for' and 'Not for' sections that guide when to use this tool. It also lists prerequisites, next steps, and related tools, providing comprehensive usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Create or update an environment variable
ā”ļø Best for: ā Setting configuration values ā Updating connection strings ā Managing service secrets
ā ļø Not for: Ć Bulk variable updates (use variable_bulk_set) Ć Temporary configuration changes
ā Prerequisites: service_list
ā Alternatives: variable_bulk_set
ā Next steps: deployment_trigger, service_restart
ā Related: variable_list, variable_delete
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the environment variable | |
| value | Yes | Value to set for the variable | |
| projectId | Yes | ID of the project containing the service | |
| serviceId | No | Optional: ID of the service for the variable, if omitted creates/updates a shared variable | |
| environmentId | Yes | ID of the environment for the variable (usually obtained from service_list) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a mutable operation (create/update) but does not detail whether the update is idempotent, if it overwrites existing values, or any permission/rate limit constraints. While not misleading, more behavioral context would be 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 well-structured using bullet points and arrows, making it scannable. Every sentence adds value (best for, not for, prerequisites, etc.). It is slightly long but justified given the guidance it provides.
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 5 parameters, no output schema, and no annotations, the description provides good contextual completeness: it explains when to use vs not, prerequisites, and related tools. It does not cover return values but that is acceptable without an output schema. Some behavioral details are missing (e.g., overwrite behavior) but overall it's fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add parameter-level details beyond what the schema already provides. For example, it mentions 'serviceId' is optional but doesn't clarify when to use it over a shared variable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create or update an environment variable', providing a specific verb and resource. It also explicitly distinguishes from sibling tool 'variable_bulk_set' in the 'Not for' section, eliminating ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Best for' and 'Not for' sections, a prerequisite ('service_list'), alternatives ('variable_bulk_set'), and even next steps ('deployment_trigger', 'service_restart'), giving clear guidance on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Create a new persistent volume for a service
ā”ļø Best for: ā Setting up database storage ā Configuring persistent data ā Adding file storage
ā ļø Not for: Ć Temporary storage needs Ć Static file hosting Ć Memory caching
ā Prerequisites: service_list
ā Next steps: volume_list
ā Related: service_update, database_deploy
| Name | Required | Description | Default |
|---|---|---|---|
| mountPath | Yes | Path where the volume should be mounted in the container | |
| projectId | Yes | ID of the project containing the service | |
| serviceId | Yes | ID of the service to attach volume to | |
| environmentId | Yes | ID of the environment for the volume (usually obtained from service_info) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only describes the action and prerequisites but does not mention permissions, rate limits, idempotency, error states, or whether the operation is destructive/reversible. This is a significant gap for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly structured with emojis, bullet points, and clear sections. Every sentence adds value without redundancy. It is concise yet comprehensive for the information it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not need to detail return values, but it could hint at the response format (e.g., volume ID). However, it effectively supplies prerequisites, next steps, and context with sibling tools, making it largely complete for a creation 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?
Input schema covers all 4 parameters with descriptions, achieving 100% coverage. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate. No extra context like formats or constraints is 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?
The description explicitly states 'Create a new persistent volume for a service' and lists specific use cases like database storage and persistent data. It distinguishes from sibling tools (volume_delete, volume_list, volume_update) with appropriate best-for/not-for categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance with 'Best for' and 'Not for' sections, lists a prerequisite (service_list), next steps (volume_list), and related tools (service_update, database_deploy). This helps the agent decide when to invoke this tool vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] Delete a volume from a service
ā”ļø Best for: ā Removing unused storage ā Storage cleanup ā Resource management
ā ļø Not for: Ć Temporary data removal Ć Data backup (use volume_backup first)
ā Prerequisites: volume_list
ā Related: service_update
| Name | Required | Description | Default |
|---|---|---|---|
| volumeId | Yes | ID of the volume to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It confirms deletion but lacks details on permissions, irreversibility, or side effects. 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?
Concise, well-organized with bullet points and emojis. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers prerequisites and related tools. For a simple delete action with one parameter, it is fairly complete, though lacks info on synchronous behavior or return value.
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 one parameter with schema covering its description fully. The description adds no extra semantic value beyond 'ID of the volume to delete'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Delete a volume from a service' with clear verb and resource. It distinguishes from related tools like volume_backup for data backup, 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?
Provides explicit best-for and not-for sections, lists prerequisites (volume_list) and related tool (service_update), giving clear guidance on when and when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[API] List all volumes in a project
ā”ļø Best for: ā Viewing persistent storage configurations ā Managing data volumes ā Auditing storage usage
ā Prerequisites: project_list
ā Next steps: volume_create
ā Related: service_info, database_deploy
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | ID of the project to list volumes for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states 'List all volumes' indicating a read operation with no destructive intent. However, it omits details such as pagination, authentication requirements, or any rate limits, which would be valuable for behavioral understanding.
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 bullet points and arrows to organize information. It front-loads the core purpose and then provides structured guidance without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a single parameter and no output schema. The description explains the purpose well but does not describe the return format, fields, or any pagination behavior. Given the simplicity, it is adequate but lacks completeness regarding output 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 100% description coverage for the single parameter projectId. The description does not add any additional meaning or constraints beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all volumes in a project' with specific verb and resource. It further clarifies use cases with bullet points for viewing configurations, managing data volumes, and auditing storage usage, which distinguishes it from sibling tools like volume_create, volume_delete, and volume_update.
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 explicit when-to-use guidance via the 'Best for' section and includes prerequisites (project_list) and next steps (volume_create). Although it does not explicitly state when not to use it, the context is sufficient for an agent to understand appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a volume's properties
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | New name for the volume | |
| volumeId | Yes | ID of the volume to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility for behavioral disclosure. It only states 'Update a volume's properties,' implying mutation, but lacks details on whether it is destructive, requires permissions, or affects other volume attributes.
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, making it concise, but it is overly brief and under-specified for a tool with two parameters. It could benefit from including more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two parameters, no output schema), the description is incomplete. It lacks usage guidelines and behavioral details, which are important 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 covers both parameters with clear descriptions (volumeId and name). The description adds no additional meaning beyond what the schema already provides, so a 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) and resource (volume), distinguishing it from sibling tools like volume_create, volume_delete, and volume_list. It is specific enough for a simple update tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites or contexts where a different tool (e.g., volume_create) would be appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes due to consistent naming, but there is some overlap among creation tools (e.g., service_create_from_image, service_create_from_repo, template_deploy) that could cause confusion. Descriptions help, but an agent might still misselect.
The majority follow a verb_noun pattern (e.g., project_create, service_list). However, some deviate like database_list_types (noun_verb_noun) and configure_api_token (verb with underscore). Overall consistent but with minor exceptions.
38 tools is excessive for typical MCP servers, which often have 10-20. While Railway is a broad platform, many tools are granular (e.g., separate tools for each CRUD operation on domains, TCP proxies, volumes) leading to an overwhelming surface.
The tool set covers most major operations for the Railway platform: projects, services, deployments, domains, variables, volumes, TCP proxies, templates. Minor gaps exist, such as no direct volume backup or database management beyond listing types and deployment.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Deploy full-stack apps (Postgres, Redis, S3, workers, backups) from Claude or curl. 59 MCP tools.
Your AI Agent's Infrastructure Layer. Connect Claude, Copilot, Codex, or ChatGPT to 200+ managed open source services. Start databases, pipelines, and applications through natural language.
Monitoring + status pages set up by talking to Claude. Auto-detects 30+ SDKs and your URLs.
Deploy and manage your apps, databases, storage, and scheduled jobs from your AI agent
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jason-tan-swe/railway-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
