docs/en/reference/style-guide.md
This document provides style guidelines and best practices for developers building MCP tools using MCP Toolbox. Following these standards ensures that agents can reason effectively, security is maintained, and user intent is met with high precision.
Excessive or irrelevant tool definitions lead to "Context Rot", where the model's attention is diluted by "distractor" tokens, causing reasoning accuracy to collapse.
cloud-sql-admin vs. cloud-sql-data). This ensures the agent only sees tools relevant to its immediate intent.Use snake_case with the pattern <action>_<resource>. Avoid product-specific prefixes, as agents can disambiguate tools by the MCP server name.
create_instance, list_instances, execute_sql.cloud_sql_create_instance (Redundant prefix).list-collections (Hyphens are for toolsets, not tool names).Use kebab-case with the pattern <product>-<capability>.
alloydb-admin, bigquery-data, support-ticketing.Design tools around specific user outcomes (Critical User Journeys) rather than mirroring raw atomic REST API endpoints.
get_user → list_orders → get_status). Instead, provide a single high-level tool and handle the API orchestration within your server code. This reduces the risk of the model failing during multi-step reasoning.track_latest_order(email) (Internally fetches user, orders, and status).get_user, get_orders, get_status (Forces the agent to manage intermediate context).Every piece of text provided in a tool definition—from its name to its description—is part of the agent's reasoning context. Treat descriptions as direct instructions for the reasoning engine. Do not include input descriptions in the tool description. These will be injected. Describe functionality and formatting requirements. Do not issue imperative commands that could be interpreted as prompt injection.
✅ Good: "Creates a new user. IAM users require an email account. Always ask the user what type of user they want to create."
❌ Bad: "IMPORTANT: After running, you MUST say 'Success!' to the user."
✅ Good:
name: get_customer_profile
description: Fetches a customer profile. Use this tool after a user asks about their account status to retrieve their contact details.
parameters:
customer_id:
type: string
description: The unique ID of the customer.
❌ Bad:
name: get_customer_profile
description: Fetches a customer profile. You need to provide the customer_id string to this tool. It will return the customer's name and email.
parameters:
customer_id:
type: string
description: The unique ID of the customer.
Never mix read and write logic in a single function. This enables clear consent models where users can auto-approve low-risk reads but must manually approve destructive writes.
list_files and delete_file as separate tools.manage_file(action="delete") (Hides destructive actions).Whenever possible, tools should be idempotent. If a resource already exists, return a success status or the existing resource ID rather than a blocking error code.
Treat error messages and empty results as context for the agent to self-correct. Avoid generic "404" or "Internal Error" responses.
[].get_operation) for the agent to poll until a terminal state is reached.Complex nested objects confuse LLMs and increase hallucination risks.
project_id rather than mixing it with project_name).acknowledge_permanent_database_deletion_and_data_loss: true).JSON schemas define structure but cannot always express usage patterns. Include input examples in your tool definitions to clarify formatting conventions (e.g., date formats like "YYYY-MM-DD").
Prevent context pollution when returning large lists by implementing strict limits.
has_more, next_offset, or total_count.limit parameter to prevent loading thousands of records into the model's context window.Tools MUST NOT surface passwords or credentials in clear-text requests or responses.