# Concepts — optimizing an external MCP toolset

> The mental model behind the `mcp-tool` capability: what the Model Context
> Protocol is, who owns which part of a tool, why only a safe edit subset is
> permitted, and why external tool metadata is untrusted. Grounded in the
> official MCP specification and security guidance.

## Contents
- 1. What MCP is
- 2. The Tool object — what the model sees
- 3. The ownership boundary (why the policy is restricted)
- 4. External tool metadata is untrusted
- 5. Practical optimization playbook
- Sources

## 1. What MCP is

The Model Context Protocol is an open standard for connecting AI applications to
external systems — "a USB-C port for AI." It defines a **client–server**
architecture over JSON-RPC 2.0:

- **MCP Host** — the AI application that coordinates one or more clients.
- **MCP Client** — a connection to one MCP server.
- **MCP Server** — a program that *provides context* to clients, exposing three
  primitives: **Tools**, Resources, and Prompts.

The host fetches the available tools from all connected servers, "combines them
into a unified tool registry that the language model can access," and the model
"automatically generates the appropriate tool calls." That is the same
select-then-fill loop as native function calling — the model sees tool
definitions and chooses one.

## 2. The Tool object — what the model sees

A server exposes tools via the `tools/list` request and they are invoked via
`tools/call`. Each **Tool** object's fields (quoted from the 2025-06-18 spec):

- `name` — "Unique identifier for the tool"
- `title` — "Optional human-readable name… for display purposes"
- `description` — "Human-readable description of functionality"
- `inputSchema` — "JSON Schema defining expected parameters"
- `outputSchema` — "Optional JSON Schema defining expected output structure"
- `annotations` — "optional properties describing tool behavior"

The model selects from `name` + `description` and fills arguments from
`inputSchema`. Tools are explicitly **"model-controlled."** This is why, on the
client side, the only things that move selection/filling are the *description*
and any *examples* you surface — and why a clear description matters as much here
as for native tools.

## 3. The ownership boundary (why the policy is restricted)

The server **owns** the implementation and the `inputSchema`. The host/client
**decides which tools to expose** to the model and can filter or annotate the
presentation. Mapped to this capability's actions:

| Edit | Who owns it | Allowed in `mcp-tool`? |
|------|-------------|:--:|
| `description`, per-param description, examples | client presentation | yes |
| which tools the model sees (`add`/`remove`) | client/host curation | yes |
| `inputSchema` (types, required, enums) | **server** | no |
| handler `code` / behavior | **server** | no |
| a new composite that runs code | needs server code | no (out of scope: server owns the code) |

A server can also change its tool list at runtime and emit
`notifications/tools/list_changed`; treat `add`/`remove` as *your curation* of the
available set, not a change to the server.

## 4. External tool metadata is untrusted

Because the description and schema come from a third party, they are **untrusted
input to the model**:

- **Tool poisoning** — a server can embed hidden instructions in a tool
  `description` that "are invisible to users but fully readable by AI models."
  The model acts on them; the user, who sees a simplified UI, never knows.
- **Shadowing** — a malicious server's tool description can alter how the model
  uses *other, trusted* tools.
- **list_changed abuse** — the spec's security annex describes a "Session Hijack
  Prompt Injection" that abuses `notifications/tools/list_changed` to enable tools
  the user wasn't aware of.

The spec itself carries a warning that clients **MUST** treat tool annotations as
untrusted unless they come from a trusted server. Operational implication for this
capability: **review every description you expose**, prefer well-known/trusted
servers, and remove tools whose metadata you can't vouch for.

### Tool annotations (the four behavior hints)
A tool's optional `annotations` are server-supplied **behavior hints** for UX and
gating, each with a default:

- `readOnlyHint` (default `false`) — the tool does not modify its environment.
- `destructiveHint` (default `true`) — may perform destructive updates; only
  meaningful when not read-only.
- `idempotentHint` (default `false`) — repeated identical calls add no further
  effect.
- `openWorldHint` (default `true`) — interacts with an external/open world (web).

They drive gating (confirm destructive ops, allow idempotent retries) but are
**hints, untrusted unless the server is trusted** — never a safety guarantee.

### Human-in-the-loop and self-correcting errors
The spec says clients SHOULD **show tool inputs before calling** and **confirm
sensitive/destructive operations** — a defense against tool-poisoning and
`list_changed` injection. And it distinguishes **execution errors** (`isError:true`
with an actionable message, surfaced to the model so it retries with fixed args)
from **protocol errors** (JSON-RPC failures the model can't act on). Encourage the
former: when you can only re-describe, document the failure mode so the model
self-corrects.

### What of §3-style output shaping is client-safe here
Documenting result fields, caps, and formats in the *description* is allowed (it's
client-side presentation). Changing the wire `inputSchema`/`outputSchema` is NOT —
that's a server change. Keep the boundary sharp: re-describe and curate, never
re-contract.

## 5. Practical optimization playbook

1. **Re-describe terse server tools** on the client side — state what/when/when-not
   and the real return shape. This is the highest-leverage edit (selection).
2. **Annotate parameter descriptions** to pin formats/limits the schema implies
   but doesn't spell out — without changing `type`/`required` (those are `schema`,
   forbidden here).
3. **Curate the exposed set** — hide overlapping/legacy tools so the needed ones
   stand out; selection degrades as the set grows.
4. **Never document capabilities the server lacks** — overpromising causes
   confident wrong calls.
5. If you need a real schema constraint or new behavior, that's a server change or an
   agent-owned wrapper optimized with the `tools` capability — out of scope here.

## Sources

- MCP Specification — Tools (Tool object fields `name`/`description`/`inputSchema`,
  `tools/list`, `tools/call`, model-controlled, `listChanged`, annotations
  untrusted): https://modelcontextprotocol.io/specification/2025-06-18/server/tools
- MCP — Architecture overview (host/client/server roles; unified tool registry;
  JSON-RPC): https://modelcontextprotocol.io/docs/learn/architecture
- MCP — Tools concept page (version-independent field definitions): https://modelcontextprotocol.io/docs/concepts/tools
- MCP — Introduction ("USB-C port for AI"; open standard): https://modelcontextprotocol.io/introduction
- Anthropic — Introducing the Model Context Protocol (Nov 25, 2024; server/client
  split): https://www.anthropic.com/news/model-context-protocol
- MCP spec/schema repository (canonical `Tool` interface in TS + JSON Schema): https://github.com/modelcontextprotocol/modelcontextprotocol
- MCP — Security Best Practices (confused deputy, token passthrough, session
  hijack via list_changed): https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices
- Invariant Labs — MCP Tool Poisoning Attacks (hidden instructions in
  descriptions; shadowing): https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks

"""mcp-tool capability — optimize an MCP toolset whose SERVER is external.

The wire schema and tool implementation belong to the MCP server, not us, so the
DEFAULT_POLICY allows only the safe subset: reword descriptions, tweak documented
params, edit examples, and add/remove tools — but NOT ``schema`` or ``code``
edits (changing the wire contract of a server you do not own would break it).
(Contrast ``tools``, which owns its code and allows the full set.)

The artifact is ``tools.json``; the materialize/apply/validate mechanics are
shared in ``cap_evolve.tool_surface`` — this module only declares the policy.
"""

from __future__ import annotations

from pathlib import Path

import _bootstrap  # noqa: F401

from cap_evolve import tool_surface

# External server → documentation + add/remove only (no schema/code).
DEFAULT_POLICY = {"allow": ["description", "params", "examples", "add", "remove"]}


def load_policy(capability_dir: Path) -> dict:
    return tool_surface.load_policy(capability_dir, DEFAULT_POLICY)


def materialize(capability_dir: Path) -> dict:
    return tool_surface.materialize(capability_dir)


def apply(capability_dir: Path, edits: list[dict] | None = None) -> dict:
    return tool_surface.apply(capability_dir, DEFAULT_POLICY, edits)


def is_empty(capability_dir: Path) -> bool:
    return tool_surface.is_empty(capability_dir)


def validate(capability_dir: Path) -> dict:
    return tool_surface.validate(capability_dir)

"""mcp-tool: by default ONLY docs + add/remove are allowed; schema/code are refused."""

from __future__ import annotations

import json
import sys
import tempfile
from pathlib import Path

import _bootstrap  # noqa: F401

import abstract


def main() -> int:
    report = {"skill": "mcp-tool", "ok": False, "problems": [], "notes": []}
    with tempfile.TemporaryDirectory() as d:
        cap = Path(d)
        (cap / "tools.json").write_text(json.dumps({"tools": [
            {"name": "lookup", "description": "Look up a record.",
             "parameters": {"type": "object", "properties": {"id": {"type": "string"}}}},
        ]}), encoding="utf-8")  # no policy.json -> default (restricted) policy

        # docs + add/remove allowed
        ok_edits = abstract.apply(cap, [
            {"tool": "lookup", "kind": "description", "value": "Look up a customer record by id."},
            {"kind": "add", "value": {"name": "ping", "description": "health check",
                                      "parameters": {"type": "object"}}},
        ])
        if ok_edits["refused"]:
            report["problems"].append(f"docs/add wrongly refused: {ok_edits['refused']}")

        # schema + code are NOT permitted for MCP tools (served by an external server)
        bad = abstract.apply(cap, [
            {"tool": "lookup", "kind": "schema", "value": {}},
            {"tool": "lookup", "kind": "code", "value": "def lookup(): ..."},
        ])
        if len(bad["refused"]) != 2:
            report["problems"].append(f"schema/code should both be refused, got {bad}")
        v = abstract.validate(cap)
        if not v["ok"]:
            report["problems"].append(f"validate failed: {v['problems']}")
        report["notes"].append("docs+add/remove allowed; schema/code refused by default")
    report["ok"] = not report["problems"]
    print(json.dumps(report, indent=2))
    return 0 if report["ok"] else 1


if __name__ == "__main__":
    sys.exit(main())

"""Expose a tools/MCP artifact as a Candidate and report policy + validity."""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

import _bootstrap  # noqa: F401

from cap_evolve import Candidate

import abstract


def main(argv=None) -> int:
    p = argparse.ArgumentParser(prog="mcp-tool")
    p.add_argument("--path", required=True, help="capability dir with tools.json (+ policy.json)")
    args = p.parse_args(argv)
    parts = abstract.materialize(Path(args.path))
    policy = abstract.load_policy(Path(args.path))
    v = abstract.validate(Path(args.path))
    cand = Candidate(id="seed", component="mcp-tool", text_parts=parts, dir=str(args.path))
    print(json.dumps({"candidate": cand.to_dict(), "policy": policy, "valid": v}, indent=2))
    return 0 if v["ok"] else 1


if __name__ == "__main__":
    sys.exit(main())

"""Thin shim: locate cap_evolve, then defer to cap_evolve._bootstrap.

Skill scripts ``import _bootstrap`` first. The real path-resolution logic lives
ONCE in ``cap_evolve._bootstrap`` (so it can't drift across skills); this shim
only has to find that package, which means a minimal upward walk for ``core/`` —
the single bit of bootstrapping that genuinely must run before cap_evolve is
importable. Everything else delegates.
"""

from __future__ import annotations

import os
import sys
from pathlib import Path


def _seed_path() -> None:
    """Minimal: put a dir containing the cap_evolve package on sys.path.

    ``CAPEVOLVE_CORE`` is honoured BEFORE any ambient import. An editable install of a
    *different* cap-evolve checkout registers a ``sys.meta_path`` finder, which outranks
    both ``sys.path`` and ``PYTHONPATH`` — so "cap_evolve imports fine" is not evidence that
    it imports the checkout you are standing in. Deferring to the ambient package here made
    an explicit override unreachable, and the symptom was a stale core silently answering
    for this one (``ModuleNotFoundError: cap_evolve.constraints`` from a checkout that
    predates that module). An explicit env var wins.
    """
    env = os.environ.get("CAPEVOLVE_CORE")
    want = Path(env).resolve() if env else None
    if want and (want / "cap_evolve" / "__init__.py").exists():
        loaded = sys.modules.get("cap_evolve")
        already = getattr(loaded, "__file__", None)
        if already and Path(already).resolve().parent.parent == want:
            return                      # right checkout already imported: touch nothing
        p = str(want)
        if p in sys.path:
            sys.path.remove(p)
        sys.path.insert(0, p)
        if loaded is not None:
            # Evicting a module makes a re-import yield a DIFFERENT object, so anything
            # already holding a reference fails an `is` check. Only ever do it when the
            # loaded package really is the wrong checkout — otherwise this "fix" becomes
            # the bug (it broke two identity assertions in core/tests exactly once).
            for name in [m for m in sys.modules
                         if m == "cap_evolve" or m.startswith("cap_evolve.")]:
                sys.modules.pop(name, None)
        for finder in list(sys.meta_path):
            if "cap_evolve" in getattr(finder, "MAPPING", {}):
                sys.meta_path.remove(finder)
        return
    # A checkout's own core outranks an ambient install. Without this, a skill script run
    # from checkout X silently executed against checkout Y's cap_evolve (an editable install
    # registers a sys.meta_path finder, which outranks sys.path), and the only symptom was
    # missing modules — or, worse, a green result measured against the wrong tree.
    here = Path(__file__).resolve()
    own = next((p / "core" for p in here.parents
                if (p / "core" / "cap_evolve" / "__init__.py").exists()), None)
    if own is not None:
        os.environ.setdefault("CAPEVOLVE_CORE", str(own))
        return _seed_path()
    try:
        import cap_evolve  # noqa: F401
        return
    except Exception:
        pass
    cands = []
    for parent in here.parents:
        cands.append(parent / "core")
        cands.append(parent)
    for c in cands:
        if (c / "cap_evolve" / "__init__.py").exists():
            p = str(c)
            if p not in sys.path:
                sys.path.insert(0, p)
            return


_seed_path()
from cap_evolve._bootstrap import ensure_core  # noqa: E402

# Anchor the upward walk at THIS skill script's location (not the core module's).
ensure_core(Path(__file__).resolve())