Designing Tools Agents Can Actually Use

# Colab cell 1 — run once. No external API needed: a stub CRM lets the
# well-designed tool actually run so you can see each branch's output.
!pip install -q mcp

from collections import namedtuple

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("crm-server")

Customer = namedtuple("Customer", "id name")
Issue = namedtuple("Issue", "id title status opened")


class _CRM:                                   # stands in for your real CRM API
    _customers = [Customer("c1", "Acme Corp"), Customer("c2", "Acme Labs"),
                  Customer("c3", "Globex")]
    _issues = {"c3": [Issue("I-9", "checkout 500s", "open", "2026-07-10"),
                      Issue("I-7", "slow search", "open", "2026-07-02")]}

    def search_customers(self, name):
        return [c for c in self._customers if name.lower() in c.name.lower()]

    def issues(self, customer_id, status="open"):
        return [i for i in self._issues.get(customer_id, []) if i.status == status]


crm = _CRM()


# BAD: the model must already know an ID, gets a raw JSON dump,
# and learns nothing from the name or description.
@mcp.tool()
def get_data(id: str) -> str:
    """Gets data."""
    return str(crm._issues.get(id))          # nested JSON dump, good luck


# GOOD: named for the task, searchable by what the model actually has
# (words, not IDs), returns shaped text, documents its own limits.
@mcp.tool()
def find_customer_issues(
    customer_name: str,
    status: str = "open",
    max_results: int = 5,
) -> str:
    """Find a customer's support issues by company name.

    Searches customers by name (fuzzy), then returns up to max_results
    issues as lines of: issue_id | title | status | opened_date.
    Use when the user asks about a customer's problems or tickets.
    NOT for creating or editing issues (use create_issue).
    If several customers match the name, returns the candidate list
    instead -- call again with a more specific name.
    """
    customers = crm.search_customers(customer_name)
    if len(customers) > 1:
        names = ", ".join(c.name for c in customers[:5])
        return (f"Ambiguous: {len(customers)} customers match. "
                f"Candidates: {names}. Call again with a full name.")
    if not customers:
        return (f"No customer found matching '{customer_name}'. "
                f"Check spelling, or try a shorter fragment of the name.")
    issues = crm.issues(customers[0].id, status=status)[:max_results]
    return "\n".join(f"{i.id} | {i.title} | {i.status} | {i.opened}"
                      for i in issues)


# @mcp.tool() leaves each a normal callable — run all three branches:
print("ambiguous ->", find_customer_issues("Acme"))
print("no match  ->", find_customer_issues("Nonexistent"))
print("success   ->\n" + find_customer_issues("Globex"))

# Colab cell 2 — run cell 1 first (it defines mcp). Stubbed log store.
from collections import namedtuple

LogLine = namedtuple("LogLine", "line")


class _LogStore:                              # stands in for your real log store
    _lines = [LogLine(f"2026-07-17T10:{i:02d}:00 ERROR timeout on shard {i}")
              for i in range(57)]             # 57 matches, to force paging

    def search(self, query):
        return [x for x in self._lines if query.lower() in x.line.lower()]


log_store = _LogStore()


@mcp.tool()
def search_logs(query: str, page: int = 1, page_size: int = 20) -> str:
    """Search application logs. Returns one page of matching lines.

    page_size max is 50. If the response says more pages exist,
    call again with page+1 -- or better, refine the query.
    """
    page_size = min(page_size, 50)                # server-enforced cap
    hits = log_store.search(query)
    total = len(hits)
    start = (page - 1) * page_size
    page_hits = hits[start:start + page_size]

    if not page_hits:
        return (f"No results on page {page} for '{query}' "
                f"({total} total). Try page 1 or broaden the query.")

    body = "\n".join(h.line[:300] for h in page_hits)   # per-item cap too
    remaining = total - (start + len(page_hits))
    if remaining > 0:
        return (f"Showing {len(page_hits)} of {total} results "
                f"(page {page}).\n{body}\n"
                f"MORE AVAILABLE: {remaining} further results -- "
                f"request page {page + 1}, or refine the query to narrow.")
    return f"Showing all {total} results.\n{body}"


# 57 matches, page_size 20 -> page 1 shows the MORE AVAILABLE trailer:
print(search_logs("timeout", page=1, page_size=20))