agent-api.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Facet MCP API",
  "version": "0.1.7",
  "description": "JSON schemas and example responses for Facet MCP tools. Used by agents for auto-discovery.",
  "tools": [
    {
      "name": "facet_plan_surface",
      "description": "Select tools for the current task under a token budget. Returns selected tools (with distilled schemas), deferred tools, before/after token counts, savings percentage, and per-tool routing reasons. Call this before each subtask instead of loading all tool schemas.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "task": {
            "type": "string",
            "description": "What the agent is trying to accomplish. Use verb + target for best results. Example: 'fix login validation bug in auth middleware'."
          },
          "tools": {
            "type": "array",
            "description": "Tool definitions to route. Omit if manifest was already registered via facet_register_manifest.",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "description": { "type": "string" },
                "inputSchema": { "type": "object" }
              },
              "required": ["name"]
            }
          },
          "budget": {
            "type": "number",
            "description": "Token budget for selected tools. Default: 6000. Increase to 10000 for multi-domain tasks.",
            "default": 6000,
            "minimum": 500,
            "maximum": 50000
          },
          "profile": {
            "type": "string",
            "description": "Named profile from facet.json (e.g. 'coding', 'review'). Profiles add preferred clusters and budget overrides."
          },
          "manifestId": {
            "type": "string",
            "description": "Cached manifest id from facet_register_manifest. Omit tools when set."
          }
        },
        "required": ["task"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "task": { "type": "string" },
          "selected": {
            "type": "array",
            "description": "Tools to use for this subtask (distilled schemas, fits within budget)",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "description": { "type": "string" },
                "inputSchema": { "type": "object" }
              }
            }
          },
          "deferred": {
            "type": "array",
            "description": "Tools held back to save tokens — re-plan with a different task to surface them",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" }
              }
            }
          },
          "tokensBefore": { "type": "integer", "description": "Total token cost of all tools before routing" },
          "tokensAfter": { "type": "integer", "description": "Total token cost of selected tools after routing" },
          "savingsPercent": { "type": "number", "description": "Percentage reduction in token cost (0–100)" },
          "reasons": {
            "type": "object",
            "description": "Per-tool routing decision — score and cluster for selected, reason for deferral",
            "additionalProperties": { "type": "string" }
          }
        }
      },
      "examples": [
        {
          "input": { "task": "fix the login validation bug", "budget": 4000 },
          "output": {
            "task": "fix the login validation bug",
            "selected": [
              {
                "name": "mcp__filesystem__read_file",
                "description": "Read the complete contents of a file...",
                "inputSchema": { "type": "object", "properties": { "path": { "type": "string" } } }
              },
              {
                "name": "mcp__filesystem__grep",
                "description": "Search file contents using regular expressions...",
                "inputSchema": { "type": "object", "properties": { "pattern": { "type": "string" } } }
              },
              {
                "name": "mcp__shell__run",
                "description": "Execute an arbitrary shell command...",
                "inputSchema": { "type": "object", "properties": { "command": { "type": "string" } } }
              },
              {
                "name": "mcp__git__diff",
                "description": "Show changes between working tree and index...",
                "inputSchema": { "type": "object", "properties": {} }
              },
              {
                "name": "mcp__git__status",
                "description": "Show working tree status...",
                "inputSchema": { "type": "object", "properties": {} }
              }
            ],
            "deferred": [
              { "name": "mcp__notion__search" },
              { "name": "mcp__slack__post_message" },
              { "name": "mcp__stripe__create_payment_intent" },
              { "name": "mcp__datadog__query_metrics" }
            ],
            "tokensBefore": 8412,
            "tokensAfter": 1240,
            "savingsPercent": 85.3,
            "reasons": {
              "mcp__filesystem__read_file": "score=0.85 cluster=filesystem",
              "mcp__filesystem__grep": "score=0.72 cluster=filesystem",
              "mcp__shell__run": "score=0.61 cluster=runtime",
              "mcp__git__diff": "score=0.54 cluster=git",
              "mcp__git__status": "score=0.48 cluster=git",
              "mcp__notion__search": "deferred: budget (350 tok)",
              "mcp__slack__post_message": "deferred: budget (290 tok)",
              "mcp__stripe__create_payment_intent": "deferred: budget (480 tok)"
            }
          }
        },
        {
          "input": { "task": "search notion for onboarding documentation", "budget": 4000 },
          "output": {
            "task": "search notion for onboarding documentation",
            "selected": [
              { "name": "mcp__notion__search" },
              { "name": "mcp__notion__get_page" },
              { "name": "mcp__filesystem__read_file" },
              { "name": "mcp__github__list_issues" }
            ],
            "deferred": [
              { "name": "mcp__shell__run" },
              { "name": "mcp__git__diff" },
              { "name": "mcp__stripe__create_payment_intent" }
            ],
            "tokensBefore": 8412,
            "tokensAfter": 1360,
            "savingsPercent": 83.8,
            "reasons": {
              "mcp__notion__search": "score=0.91 cluster=notion",
              "mcp__notion__get_page": "score=0.77 cluster=notion",
              "mcp__filesystem__read_file": "score=0.42 cluster=filesystem",
              "mcp__github__list_issues": "score=0.21 cluster=github",
              "mcp__shell__run": "deferred: budget (310 tok)",
              "mcp__git__diff": "deferred: budget (220 tok)"
            }
          }
        }
      ]
    },
    {
      "name": "facet_audit_tools",
      "description": "Measure token cost and capability clusters for a tool manifest. Use at session start to understand your baseline overhead before calling facet_plan_surface.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "tools": {
            "type": "array",
            "description": "Tool definitions to audit",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "description": { "type": "string" },
                "inputSchema": { "type": "object" }
              },
              "required": ["name"]
            }
          }
        },
        "required": ["tools"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "totalTools": { "type": "integer" },
          "totalTokens": { "type": "integer" },
          "entries": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "tool": { "type": "object" },
                "tokens": { "type": "integer" },
                "cluster": { "type": "string" }
              }
            }
          },
          "clusters": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "label": { "type": "string" },
                "toolCount": { "type": "integer" },
                "tokens": { "type": "integer" }
              }
            }
          }
        }
      },
      "examples": [
        {
          "input": { "tools": [{ "name": "mcp__filesystem__read_file" }, { "name": "mcp__git__diff" }] },
          "output": {
            "totalTools": 2,
            "totalTokens": 540,
            "entries": [
              { "tool": { "name": "mcp__filesystem__read_file" }, "tokens": 320, "cluster": "filesystem" },
              { "tool": { "name": "mcp__git__diff" }, "tokens": 220, "cluster": "git" }
            ],
            "clusters": [
              { "id": "filesystem", "label": "filesystem", "toolCount": 1, "tokens": 320 },
              { "id": "git", "label": "git", "toolCount": 1, "tokens": 220 }
            ]
          }
        }
      ]
    },
    {
      "name": "facet_register_manifest",
      "description": "Cache the full tool manifest server-side so facet_plan_surface can re-plan cheaply across subtasks without re-sending the full tool list each time. Call once at session start.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Optional manifest id (default: auto-generated)"
          },
          "tools": {
            "type": "array",
            "description": "Full tool manifest to cache",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "description": { "type": "string" },
                "inputSchema": { "type": "object" }
              },
              "required": ["name"]
            }
          }
        },
        "required": ["tools"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "manifestId": { "type": "string", "description": "Id to pass to facet_plan_surface and facet_audit_tools" },
          "registered": { "type": "integer", "description": "Number of tools cached" },
          "totalTokens": { "type": "integer", "description": "Total token cost of the cached manifest" }
        }
      },
      "examples": [
        {
          "input": { "tools": [{ "name": "mcp__filesystem__read_file" }, { "name": "mcp__git__diff" }] },
          "output": { "manifestId": "m1", "registered": 2, "totalTokens": 540 }
        }
      ]
    }
  ],
  "mcpConfig": {
    "command": "npx",
    "args": ["-y", "@kioie/facet", "mcp"]
  },
  "agentWorkflow": {
    "steps": [
      "1. Call facet_register_manifest(tools) — once, at session start",
      "2. Call facet_plan_surface(task, budget=6000) — before each subtask",
      "3. Use ONLY the tools in selected[] for this subtask",
      "4. Task changes? Call facet_plan_surface again with the new task string."
    ],
    "note": "Always re-plan when the task domain shifts (e.g. coding → documentation → ops). Routing is cheap; re-plan liberally."
  }
}