Provides web search capabilities through DuckDuckGo, allowing AI agents to perform internet searches and retrieve search results.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agentic-terminal run ls -la in the current directory and summarize the output"
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 comprehensive, hands-on course that teaches you everything about Model Context Protocol (MCP) - from creating your first MCP server to deploying production-ready applications using Docker and cloud-native architectures.
Related MCP server: mcp2term
Model Context Protocol (MCP) is a standardized protocol that enables seamless communication between AI models and external tools/systems. It allows:
š Tool Integration: Connect AI models to custom tools and services
š Universal Communication: Standardized way for LLMs to interact with resources
š Multi-Transport Support: Use stdio, HTTP, or custom transports
š”ļø Type-Safe: Full type support and validation
š” Remote Execution: Execute tools on remote servers
This masterclass takes you on a complete journey through MCP development:
Beginner āā Intermediate āā Advanced āā Production
ā ā ā ā
CH-1 CH-2,3 CH-4,5 CH-6Whether you're an AI enthusiast, developer, or DevOps engineer, this course has something for you!
Python 3.12+ (MCP requires modern Python)
Git for version control
Docker (for Chapter 6)
Basic Python knowledge (async/await, decorators)
API familiarity (helpful for understanding HTTP transport)
Terminal/Command Line comfort
git clone https://github.com/yourusername/MCP_Masterclass.git
cd MCP_MasterclassUsing uv (recommended - faster than pip):
uv venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activateOr using traditional venv:
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activateuv pip install -r pyproject.toml
# or
pip install -e .The project includes:
fastmcp - FastMCP framework for building MCP servers
langchain - For integration with language models
langchain-mcp-adapters - Bridge between LangChain and MCP
mcp - Official MCP specification implementation
agentic-terminal - Terminal-based MCP tools
python main.py
# Expected output: "Hello from mcp-masterclass!"File: CH-1_CreateMCP/
Learn the fundamentals of MCP by building a basic server:
1_first_mcpserver_stdio.py: Build a simple MCP server using stdio transport
Basic tool definition with @mcp.tool() decorator
Fetch and process data patterns
Running server locally
2_python_client.py: Create a Python client to connect to the MCP server
Understand client-server communication
Making tool calls programmatically
3_langchain_client.py: Integrate MCP with LangChain
Use MCP tools with language models
Automatic tool discovery and binding
Key Learnings:
FastMCP framework basics
Stdio transport protocol
Async function handling
Tool documentation with docstrings
File: CH-2_HTTP_MCP/
Scale your MCP servers for real-world applications:
1_http_mcp.py: Build an HTTP-based MCP server
Streamable HTTP transport
Network accessibility
Multi-client support
Running on port 8050
2_langchain_client.py: Connect LangChain to HTTP MCP server
Remote server communication
HTTP client setup
Tool availability over network
Key Learnings:
HTTP transport vs Stdio
Scalability considerations
Network security basics
Multi-client architectures
File: CH-3_3rdParty_MCPs/
Leverage community MCP servers in your applications:
community_mcp.py: Use open-source community MCP servers
Discovering available MCPs
Integration patterns
Popular community tools
tavily_mcp.py: Integrate Tavily search MCP
Real-world API integration
Web search capabilities
Data enrichment workflows
Key Learnings:
MCP ecosystem exploration
Third-party tool integration
Composition and orchestration
API key management
File: CH-4_PyPI_MCP/ & MCP_PYPI/
Package and distribute your MCP as a Python package:
1_test_package.py: Test your packaged MCP
2_client.py: Use the published package as a client
MCP_PYPI/: Complete package structure
pyproject.toml: Package configuration
src/agentic_terminal/: Agentic terminal implementation
tools.py: Custom tool definitions
main.py: Entry point
Key Learnings:
Python package structure
PyPI publishing workflow
Package versioning and dependency management
Entry points and CLI tools
File: CH-5_MCP_Gateway/
Build a unified gateway to manage multiple MCP servers:
gateway.py: Central gateway for orchestrating multiple MCPs
Mounting multiple MCP servers
Request routing
Tool discovery and aggregation
Unified interface to many tools
Example: integrating duckduckgo-mcp-server
Key Learnings:
Gateway pattern architecture
MCP composition and mounting
Load balancing concepts
Tool proxy implementations
File: CH-6_MCP_Docker/
Deploy MCP servers in production using Docker:
Dockerfile: Multi-stage Docker configuration
Base image: Python 3.11-slim
Pre-installed tools (duckduckgo-mcp-server, agentic_terminal)
FastMCP runtime
requirements.txt: Python dependencies for container
app/gateway.py: Gateway application for containerized deployment
Key Learnings:
Dockerfile best practices
Multi-stage builds
Container environment setup
Production deployment patterns
Tool availability in containers
MCP_Masterclass/
ā
āāā CH-1_CreateMCP/ # Basics: Stdio-based MCP
ā āāā 1_first_mcpserver_stdio.py
ā āāā 2_python_client.py
ā āāā 3_langchain_client.py
ā
āāā CH-2_HTTP_MCP/ # HTTP Transport & Scalability
ā āāā 1_http_mcp.py
ā āāā 2_langchain_client.py
ā
āāā CH-3_3rdParty_MCPs/ # Integration Patterns
ā āāā community_mcp.py
ā āāā tavily_mcp.py
ā
āāā CH-4_PyPI_MCP/ # Packaging
ā āāā 1_test_package.py
ā āāā 2_client.py
ā
āāā CH-5_MCP_Gateway/ # Orchestration
ā āāā gateway.py
ā
āāā CH-6_MCP_Docker/ # Production Deployment
ā āāā Dockerfile
ā āāā requirements.txt
ā āāā app/
ā āāā gateway.py
ā
āāā MCP_PYPI/ # PyPI Package Structure
ā āāā pyproject.toml
ā āāā README.md
ā āāā src/
ā āāā agentic_terminal/
ā āāā __init__.py
ā āāā main.py
ā āāā tools.py
ā
āāā Notes/ # Course Notes
ā āāā MCP-Masterclass.png
ā
āāā pyproject.toml # Main project config
āāā package.json # NPM metadata
āāā main.py # Entry point
āāā README.md # This fileStart with basics (stdio servers)
Progress to HTTP scalability
Learn composition and orchestration
Deploy with Docker
Every concept includes working code
Multiple integration patterns
Real-world scenarios (search, processing)
Docker containerization
Gateway architecture
Multi-server orchestration
PyPI packaging
Third-party MCP servers
Popular tools (Tavily, DuckDuckGo)
Integration patterns
Extensibility examples
Technology | Purpose | Version |
FastMCP | MCP framework | 3.2.4+ |
Python | Programming language | 3.12+ |
Docker | Containerization | Latest |
LangChain | LLM framework integration | 1.2.17+ |
Async/Await | Concurrent operations | Built-in Python |
HTTP | Network transport | Standard |
Stdio | Local process communication | Standard |
UV | Package management | Latest |
# Navigate to Chapter 1
cd CH-1_CreateMCP
# Activate your virtual environment
source .venv/bin/activate # or .venv\Scripts\activate on Windows
# Run the MCP server
python 1_first_mcpserver_stdio.py# In another terminal, with venv activated
cd CH-1_CreateMCP
python 2_python_client.pycd CH-1_CreateMCP
python 3_langchain_client.pycd CH-2_HTTP_MCP
python 1_http_mcp.py
# Server runs on http://localhost:8050cd CH-5_MCP_Gateway
python gateway.pycd CH-6_MCP_Docker
docker build -t mcp-masterclass .
docker run -p 8050:8050 mcp-masterclassInstall all dependencies: uv pip install -r pyproject.toml
Ensure Python 3.12+ is active: python --version
Set any required API keys in environment variables
Each chapter can be run independently:
# Chapter 1 - Basic Server
cd CH-1_CreateMCP && python 1_first_mcpserver_stdio.py
# Chapter 2 - HTTP Server
cd CH-2_HTTP_MCP && python 1_http_mcp.py
# Chapter 5 - Gateway
cd CH-5_MCP_Gateway && python gateway.py
# Chapter 6 - Docker
cd CH-6_MCP_Docker && docker build -t mcp . && docker run mcpEnable verbose output for MCP debugging:
# Set debug environment variable
export MCP_DEBUG=1
python your_mcp_file.pyA: No, MCP servers run on CPU. GPU is only needed if running large language models locally.
A: Yes! MCP is framework-agnostic. It works with any LLM framework that supports the MCP protocol.
A:
Stdio: Local communication, lower latency, single machine
HTTP: Network communication, scalable, accessible remotely
A: Use the @mcp.tool() decorator:
@mcp.tool()
async def my_tool(param: str):
"""Tool description."""
return {"result": "your result"}A: Yes! The project includes Docker containerization and gateway patterns for production deployment.
A: Tools can make HTTP calls internally. See Chapter 3 for Tavily integration example.
A: Yes! Use the gateway pattern (Chapter 5) to orchestrate multiple servers.
A: It allows others to install and use your MCP server as a package: pip install your-mcp-server
MCP GitHub Repository
FastMCP GitHub Issues
LangChain Discord Community
MCP Tool Creation Best Practices
LLM Integration Patterns
Docker & Kubernetes for AI
Beginner: Read Chapter 1-2 documentation
Intermediate: Work through Chapter 3-4 examples
Advanced: Study Chapter 5-6 architecture
Expert: Extend with your own MCPs
Solution: Ensure Python 3.12+ is installed
python --version # Should show 3.12.x or higherSolution: Reinstall dependencies
uv pip install --force-reinstall fastmcpSolution: Use a different port or kill the process
# On Windows
netstat -ano | findstr :8050
# On Linux/Mac
lsof -i :8050Solution: Clear Docker cache and rebuild
docker system prune -a
docker build --no-cache -t mcp-masterclass .We welcome contributions! Areas for enhancement:
Additional example MCPs
Documentation improvements
Additional transport protocols
Testing suite expansion
Deployment examples (Kubernetes, Cloud Run, etc.)
After completing this masterclass, you will be able to:
ā Create and deploy MCP servers using FastMCP ā Understand and implement different transport protocols ā Integrate with LangChain and other frameworks ā Compose multiple MCPs into orchestrated systems ā Package and publish MCP tools to PyPI ā Deploy MCPs using Docker and containerization ā Design scalable, production-ready MCP architectures ā Troubleshoot and debug MCP applications
This function will execute a bash command and return the output. This function is useful for executing bash commands including creating files, directories, and other bash commands.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes |
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 mentions creating files and directories, but omits that bash can modify, delete, or affect the system in unintended ways. No working directory, permissions, or error handling details are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences and front-loads the core action in the first sentence. The second sentence adds redundant phrasing ('other bash commands') but does not significantly impede understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that executes arbitrary bash commands, the description lacks important context such as return format, error behavior, environment, and side-effect warnings. The absence of an output schema and annotations makes this a substantial gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema's only parameter 'command' has no description, and the tool description merely echoes 'bash command' without explaining syntax, examples, or constraints. With 0% schema description coverage, this fails to compensate for the missing parameter semantics.
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 'will execute a bash command and return the output', specifying the verb 'execute' and the resource 'bash command'. It distinguishes bash from siblings like python_code and write_file, though it does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use bash versus alternatives such as python_code, write_file, or create_folder. The phrase 'useful for executing bash commands including creating files, directories' offers examples but no selection criteria, exclusions, or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This function will create a folder with the given name. If the folder already exists, it will return a message indicating that the folder already exists.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It mentions the key behavior of returning a message if the folder already exists, which is useful. However, it does not disclose other relevant behaviors such as whether parent directories are created, error handling, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core function and a conditional behavior. It is front-loaded and contains no filler or redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no annotations/output schema, the description covers the basic operation but omits important operational details such as path resolution, error behavior, and return types. It also does not indicate when this tool should be preferred over sibling tools, making it adequate but 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?
The only parameter 'folder' has no schema description, and the description only refers to 'the given name,' adding little beyond the schema's name and type. It does not clarify whether this should be a full path, relative path, or just a folder name, leaving important ambiguity.
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 creates a folder with a given name and adds the idempotency behavior (returns a message if the folder exists). This is specific and distinguishes it from siblings like delete_folder or write_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like bash (which could use mkdir) or python_file. There is no mention of prerequisites, path handling, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This function will delete a folder with the given name. If the folder does not exist, it will return a message indicating that the folder does not exist.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It only mentions behavior when the folder does not exist, missing success behavior, permission requirements, or whether deletion is recursive. This is minimal coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action, and includes a conditional edge case. Every sentence earns its place with 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?
For a simple tool with one parameter and no output schema, the description covers the core action and one edge case. However, it omits return behavior on success and any side effects, making it only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'folder' with no description (0% coverage). The description clarifies that the parameter is the folder's name ('with the given name'), adding some meaning beyond the schema. However, it does not provide format or validation details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a folder by name, using the specific verb 'delete' and resource 'folder'. It distinguishes from siblings like create_folder by its destructive action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating its function, but does not explicitly mention when to prefer this tool over alternatives or any conditions (e.g., safety checks, prerequisites). It provides clear context but no exclusions or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This function will return a list of files that match the given pattern. This function is useful for finding files in a directory.
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states that a list of files is returned, but does not mention recursion, pattern syntax, hidden files, error handling, or the read-only nature. This is a significant transparency gap for a tool that lacks annotation support.
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 front-loaded with the core purpose in the first sentence. However, the second sentence ('This function is useful for finding files in a directory') is somewhat redundant and could be removed, but it is not excessively verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is too sparse. It fails to cover glob syntax, pattern examples, return behavior (e.g., empty list on no match), and any limitations. A simple tool still benefits from a few more details to be complete enough for an AI 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?
The schema_description_coverage is 0% and the description does not compensate. The only parameter 'pattern' is referred to as 'the given pattern' without explaining that it is a glob pattern, its syntax, or examples. The description adds no useful semantic value beyond the schema's field name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: returning a list of files that match a given pattern. It also mentions 'finding files in a directory', which distinguishes it from sibling tools like grep (content search) or read_file (file access).
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 statement 'useful for finding files in a directory' provides some context but does not explicitly mention alternatives or when not to use this tool. It does not name grep or bash as alternatives, so it falls short of explicit usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This function will search for the given pattern in the specified file and return the matching lines.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| pattern | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It states the core behavior (search and return matching lines) but does not mention potential details like regex handling, case sensitivity, or error behavior, leaving moderate gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and directly states purpose. There is no redundant information or filler, making it appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but with no annotations, no output schema, and no parameter descriptions, the description is somewhat thin. It covers the main function but omits details like return format and edge cases, leaving the agent with unanswered questions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate by explaining the parameters. It only names 'pattern' and 'specified file' in a generic way, adding little meaning beyond the schema's property names. The description does not clarify pattern syntax or file path format.
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 searches for a pattern in a file and returns matching lines, which identifies the verb, resource, and result. However, it does not explicitly distinguish itself from siblings like bash or read_file, so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as bash, read_file, or glob. No context is given about suitable scenarios or exclusions, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This function will execute a python code and return the output.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It only mentions execution and returning output, omitting details about side effects, execution environment, error handling, or whether the output is stdout, stderr, or an exit code.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently states the core action and result, making it appropriately 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 the lack of annotations, output schema, and the inherent complexity of a code execution tool, the description is insufficient. The agent is not informed about the output shape, potential side effects, or safety considerations, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one 'code' parameter with no description, and the description clarifies that it represents the Python code to execute. This adds meaning beyond the schema, but does not provide constraints like size or format specifics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool executes Python code and returns output, using a specific verb and resource. However, it does not differentiate from sibling tools like python_file or bash, so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as bash or python_file. It lacks any context about preferred use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This function will execute a python file and return the output.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It only says it executes and returns output, but does not explain how errors are handled, what 'output' includes (stdout, stderr, exit code), whether execution is synchronous, or any side effects. This is a significant gap for a code execution 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 a single sentence that is concise and front-loaded with the core action. There is no wasted wording or redundant information. It is appropriately sized for a simple one-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations and no output schema, the description should provide more operational context. It omits critical details like error behavior, return format, and environment requirements. While the tool is simple, the lack of behavioral disclosure makes it incomplete for an AI agent to invoke safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not clarify the 'file' parameter beyond its name. It does not state whether 'file' is a path, content, or how paths are resolved. The description adds no meaningful param detail beyond what the schema already implies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'execute a python file and return the output.' It uses a specific verb ('execute') and resource ('python file'), and it differentiates from sibling tools like python_code (which likely runs code snippets) and bash (which runs shell commands) by focusing on file execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., Python installed), when choosing it over python_code or bash, or any exclusions. There is no explicit 'when to use' or 'when not to use' context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This function will read the contents of a file and return it as a string.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It merely restates the tool's name and basic action without disclosing error behavior, encoding handling, or safety properties. The description adds minimal value beyond the tool name itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded and directly states the action and return type. Every word is necessary and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with no output schema, the description does explain the return type (string). However, it lacks detail on edge cases like missing files, permission errors, or path interpretation, which an agent may need. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'file' has 0% schema description coverage, and the description does not specify whether it expects a path, URI, or file name. The description provides no additional meaning to the parameter beyond its name, leaving the agent to guess.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a file's contents and returns them as a string, which is a specific verb-resource pair. It distinguishes itself from siblings like write_file (write), grep (search), and glob (list files by pattern).
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 usage is implied: use when you need the full contents of a file. However, there is no explicit guidance on when not to use it or mention of alternatives like grep for searching, so it does not fully differentiate from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This function will write the given content to a file. If the file does not exist, it will be created.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| content | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the auto-create behavior ('If the file does not exist, it will be created'), which is valuable. However, it does not mention whether existing files are overwritten or appended, nor any path or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and front-loaded, stating the primary function and the key creation behavior. 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?
While the tool is simple and the description covers the main purpose, it lacks important details such as overwrite behavior and path handling. Given no annotations and no output schema, the description is minimally viable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only vaguely maps 'given content' to the content parameter and 'to a file' to the file parameter. No details are given about path formats, expected content type, or behavior for special paths.
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 writes content to a file, using the specific verb 'write' and resource 'file'. It also mentions creation if the file does not exist, which distinguishes it from read_file and other file-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to write or create files) and the context is clear given sibling tools like read_file and create_folder. However, it does not explicitly mention when not to use it or name alternatives, so it falls slightly short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0bashcreate_folderdelete_folderglobgreppython_codepython_fileread_filewrite_fileScored across 9 tools
Most tools have clearly distinct purposes (file read/write, folder creation/deletion, search, execution). The main overlap is between bash, python_code, and python_file, all of which execute code, but their descriptions clarify the intended runtime and usage.
Naming conventions are mixed: bare Unix-style commands (bash, glob, grep), noun-noun compounds (python_code, python_file), and verb-noun phrases (read_file, write_file, create_folder, delete_folder). The pattern is not consistent but remains readable and predictable.
Nine tools is well-scoped for an agentic terminal server. It covers execution, file operations, search, and directory management without excessive redundancy or an unwieldy surface area.
The set covers core terminal workflows: running commands/code, reading/writing files, creating/deleting folders, and searching. Notable missing operations like delete_file, move/copy, and listing directories are minor gaps since bash can handle them.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Automate 1,000+ services from any MCP-compatible AI agent: build Applets, run actions and queries.
