Skip to main content

MCP Tools in Agents

When MCP servers are assigned to an agent, their tools become available to the LLM during execution. This page explains how discovered tools work and how to write system prompts that effectively use them.

Tool Discovery at Runtime​

Each time an agent node runs (in a workflow or test console), TARX:

  1. Reads the agent's mcp_servers list
  2. Connects to each MCP server
  3. Sends tools/list to discover available tools
  4. Adds each discovered tool to the LLM's tool list alongside built-in capabilities

The entire discovery process takes 50-200ms per server.

Tool Naming Convention​

MCP tools are namespaced by the server's instance name to avoid conflicts:

{instance_name}__{tool_name}

Example: If you connected a GitHub MCP server named github, its create_pull_request tool becomes:

github__create_pull_request

The LLM sees this full namespaced name in its tool list.

Tool Definition Passed to LLM​

Each MCP tool is presented to the LLM as a function definition:

{
  "type": "function",
  "function": {
    "name": "github__create_pull_request",
    "description": "Create a new pull request in a GitHub repository",
    "parameters": {
      "type": "object",
      "properties": {
        "repo": {
          "type": "string",
          "description": "Repository name (owner/repo format)"
        },
        "title": {
          "type": "string",
          "description": "Pull request title"
        },
        "body": {
          "type": "string",
          "description": "Pull request description"
        },
        "head": {
          "type": "string",
          "description": "The branch containing the changes"
        },
        "base": {
          "type": "string",
          "description": "The branch to merge into"
        }
      },
      "required": ["repo", "title", "head", "base"]
    }
  }
}

The LLM uses this schema to know what arguments to provide when calling the tool.

Writing System Prompts for MCP Agents​

Describe the Available Tools​

LLMs perform better when the system prompt mentions what tools are available and when to use them:

You are a developer assistant with access to GitHub via MCP tools.

Available tools:
- github__list_repositories: List repos you have access to
- github__get_file_contents: Read any file from a repo
- github__create_pull_request: Open a PR after making changes
- github__create_issue: File a bug or feature request

Workflow for code changes:
1. Use github__get_file_contents to read the relevant files first
2. Analyze the code and plan the changes
3. After changes are implemented, use github__create_pull_request
4. Include a clear description of what changed and why

Set Tool Usage Policies​

When creating PRs:
- Always target the 'main' branch unless told otherwise
- PR titles should follow conventional commit format: type(scope): description
- PR bodies should include: What changed, Why, How to test

When reading files:
- Read the file before making any suggestions about it
- If you're unsure of the file structure, use github__list_repositories to explore

Handle Tool Errors​

If a tool call fails:
- Report the error clearly to the user
- Suggest what information might be missing (wrong repo name, insufficient permissions, etc.)
- Do not retry silently — always explain what went wrong

Tool Call Flow in Practice​

Example: An agent with GitHub MCP, asked to "Create a PR for the authentication fix branch"

Agent reasoning (internal):
1. I need to create a PR. I should check what repos are available first.
   → calls github__list_repositories
   → result: ["myorg/backend", "myorg/frontend", "myorg/docs"]

2. User said "authentication fix" — likely the backend repo.
   Let me check the branches.
   → calls github__list_branches(repo="myorg/backend")
   → result: ["main", "feature/auth-fix", "feature/user-management"]

3. Found it: "feature/auth-fix". Creating PR targeting main.
   → calls github__create_pull_request({
       repo: "myorg/backend",
       title: "fix(auth): resolve JWT validation issue",
       body: "## What\nFixes JWT expiry check...\n\n## Why\n...",
       head: "feature/auth-fix",
       base: "main"
     })
   → result: {url: "https://github.com/myorg/backend/pull/42", number: 42}

Agent response:
"I've created PR #42 'fix(auth): resolve JWT validation issue' targeting main.
You can review it at: https://github.com/myorg/backend/pull/42"

Tool Round Limits​

TARX limits agents to 10 tool rounds per execution. A "round" is one tool call + result. If an agent needs more than 10 calls:

  • Simplify the task — break it into multiple workflow nodes (each gets 10 rounds)
  • Improve the system prompt to make the agent more efficient
  • Contact support to discuss increasing the limit for your use case

Combining MCP with Capabilities​

MCP tools and built-in capabilities work together. An agent could:

  1. Use web_search (capability) to find the latest documentation
  2. Use web_scraper (capability) to read a relevant page in full
  3. Use github__create_issue (MCP) to file an issue with the findings
  4. Use jira__create_issue (MCP) to create a Jira ticket with the results

The LLM decides which tool to use for each sub-task.

Real-World Examples​

Code Review Agent​

System prompt:
You are an automated code reviewer. When given a PR URL or PR number:
1. Use github__get_pull_request to fetch the PR details
2. Use github__list_pull_request_files to see changed files
3. Use github__get_file_contents to read each changed file
4. Analyze for: bugs, security issues, style, test coverage
5. Use github__create_pull_request_review to submit your review

Always: Be constructive, cite specific lines, and distinguish between 
blocking issues (must fix) and suggestions (nice to have).

Jira-Driven Sprint Planner​

System prompt:
You are a sprint planning assistant. 
1. Use jira__list_issues(project="MYPROJECT", status="Backlog") to see available work
2. Ask the user for sprint capacity (story points)
3. Prioritize and suggest sprint items based on priority and estimate
4. When the user approves the selection, use jira__update_issue to move each to "In Sprint"

Database Reporter​

System prompt:
You answer questions about our product database.
1. Use postgres__list_tables to understand available data
2. Use postgres__describe_table to understand column structure  
3. Use postgres__query to retrieve the relevant data (SELECT only — never modify)
4. Present results in a clear, human-readable format

Never: Run INSERT, UPDATE, DELETE, or DDL statements.
If asked to modify data, explain that you have read-only access and suggest 
the appropriate team to contact.
Last updated on