Tool Design & MCP Integration

1{
2  "name": "lookup_customer",
3  "description": "Search for a customer by email, phone number, or account ID. Returns customer profile including name, account status, and order history summary. Input: exactly ONE of email, phone, or account_id. Email must contain @. Phone must be E.164 format (e.g., +15551234567). Account ID must start with ACC-. Returns: customer object or empty array if not found. Note: empty result means customer not found, this is NOT an error.",
4  "input_schema": {
5    "type": "object",
6    "properties": {
7      "email": {
8        "type": "string",
9        "description": "Customer email address (must contain @)"
10      },
11      "phone": {
12        "type": "string",
13        "description": "Phone in E.164 format, e.g., +15551234567"
14      },
15      "account_id": {
16        "type": "string",
17        "description": "Account ID starting with ACC-, e.g., ACC-12345"
18      }
19    }
20  }
21}

1{
2  "access_failure_example": {
3    "isError": true,
4    "errorCategory": "timeout",
5    "isRetryable": true,
6    "context": {
7      "attempted": "Customer lookup by email: user@example.com",
8      "service": "customer-database",
9      "timeout_ms": 5000,
10      "suggestion": "Retry after 2 seconds or try account ID lookup"
11    }
12  },
13  "empty_result_example": {
14    "isError": false,
15    "customers": [],
16    "metadata": {
17      "searched_by": "email",
18      "query": "user@example.com",
19      "results_count": 0
20    }
21  }
22}

1# WRONG: One agent with too many tools
2overloaded_agent = Agent(
3    tools=[
4        lookup_customer, update_account, verify_identity,
5        find_order, process_refund, update_shipping,
6        track_package, send_email, send_sms,
7        create_ticket, escalate, search_kb,
8        check_inventory, apply_coupon, schedule_callback,
9        log_interaction, generate_report, update_preferences,
10    ]  # 18 tools — selection quality degrades!
11)
12
13# CORRECT: Coordinator + specialized subagents
14coordinator = Agent(
15    tools=[Task, summarize_results, format_response],  # 3 tools
16)
17customer_agent = Agent(
18    tools=[lookup_customer, update_account, verify_identity, check_status],
19)
20order_agent = Agent(
21    tools=[find_order, process_refund, update_shipping, track_package],
22)
23comms_agent = Agent(
24    tools=[send_email, send_sms, create_ticket, escalate_human],
25)

1{
2  "mcpServers": {
3    "jira": {
4      "command": "npx",
5      "args": ["@company/jira-mcp-server"],
6      "env": {
7        "JIRA_URL": "${JIRA_URL}",
8        "JIRA_TOKEN": "${JIRA_TOKEN}"
9      }
10    },
11    "postgres": {
12      "command": "npx",
13      "args": ["@company/pg-mcp-server", "--read-only"],
14      "env": {
15        "DATABASE_URL": "${DATABASE_URL}"
16      }
17    }
18  }
19}

1Task: "Read the configuration file"
2  Correct: Read("config.json")
3  Wrong:   Bash("cat config.json")
4
5Task: "Create a new test file"
6  Correct: Write("tests/new-test.ts", content)
7  Wrong:   Bash("echo '...' > tests/new-test.ts")
8
9Task: "Fix a bug in line 42 of server.ts"
10  Correct: Edit("server.ts", old_text, new_text)
11  Wrong:   Write("server.ts", entire_file_content)
12
13Task: "Find all usages of getUserById"
14  Correct: Grep("getUserById", "src/")
15  Wrong:   Bash("grep -r 'getUserById' src/")
16
17Task: "Find all TypeScript test files"
18  Correct: Glob("**/*.test.ts")
19  Wrong:   Bash("find . -name '*.test.ts'")
20
21Task: "Run the test suite"
22  Correct: Bash("npm test")
23  (No built-in alternative — Bash is correct here)