Self-Inspect Tools

Tools for agents to inspect their own identity, permissions, and usage.

Available Tools

Tool	Description	Permission
self_inspect/whoami	Get agent identity and permissions	Always allowed
self_inspect/get_my_usage	Get current session/daily usage	Always allowed
self_inspect/list_my_tools	List available tools	Always allowed

TIP

Self-inspect tools are always available to agents—no explicit permission required.

self_inspect/whoami

Get information about the current agent's identity and permissions.

Parameters

None required.

Example

from gateflow_mcp import MCPClient

client = MCPClient(agent_id="agent_abc123", api_key="gf-agent-...")

result = client.call_tool(
    name="self_inspect/whoami",
    arguments={}
)

print(f"Agent: {result['name']} ({result['agent_id']})")
print(f"Status: {result['status']}")
print(f"Permissions:")
print(f"  Tools: {result['permissions']['tools']}")
print(f"  Models: {result['permissions']['models']}")

Response

{
  "agent_id": "agent_abc123",
  "name": "Support Bot",
  "description": "Customer support assistant",
  "status": "active",
  "created_at": "2026-02-01T10:00:00Z",
  "permissions": {
    "tools": [
      "llm/chat",
      "retrieval/search",
      "retrieval/rerank"
    ],
    "models": [
      "gpt-5-mini",
      "gpt-5.2"
    ],
    "data_classification": [
      "public",
      "internal"
    ],
    "collections": [
      "support-docs",
      "product-docs"
    ]
  },
  "limits": {
    "cost_per_session": 5.00,
    "cost_daily": 100.00,
    "requests_per_minute": 60
  },
  "metadata": {
    "team": "support",
    "environment": "production"
  }
}

self_inspect/get_my_usage

Get current usage statistics for the session and billing period.

Parameters

Parameter	Type	Required	Description
period	string	No	session, daily, monthly, or all

Example

result = client.call_tool(
    name="self_inspect/get_my_usage",
    arguments={"period": "all"}
)

print(f"Session cost: ${result['session']['cost']:.4f}")
print(f"Daily cost: ${result['daily']['cost']:.2f} / ${result['limits']['cost_daily']:.2f}")
print(f"Tools called: {result['session']['tool_calls']}")

Response

{
  "session": {
    "session_id": "sess_xyz789",
    "started_at": "2026-02-16T10:00:00Z",
    "duration_seconds": 300,
    "tool_calls": 15,
    "cost": 0.45,
    "tokens": {
      "prompt": 5000,
      "completion": 2000
    }
  },
  "daily": {
    "date": "2026-02-16",
    "tool_calls": 250,
    "cost": 12.50,
    "remaining_budget": 87.50
  },
  "monthly": {
    "month": "2026-02",
    "tool_calls": 5000,
    "cost": 350.00
  },
  "limits": {
    "cost_per_session": 5.00,
    "cost_daily": 100.00,
    "cost_monthly": 2000.00
  },
  "warnings": []
}

Usage Warnings

When approaching limits:

{
  "warnings": [
    {
      "type": "daily_budget",
      "message": "Daily budget is 85% used",
      "current": 85.00,
      "limit": 100.00,
      "percentage": 0.85
    }
  ]
}

self_inspect/list_my_tools

List all tools available to the agent.

Parameters

Parameter	Type	Required	Description
category	string	No	Filter by category
include_schema	boolean	No	Include input schemas

Example

result = client.call_tool(
    name="self_inspect/list_my_tools",
    arguments={
        "include_schema": True
    }
)

for tool in result["tools"]:
    print(f"{tool['name']}: {tool['description']}")
    if tool.get('schema'):
        print(f"  Parameters: {list(tool['schema']['properties'].keys())}")

Response

{
  "tools": [
    {
      "name": "llm/chat",
      "category": "llm",
      "description": "Send messages to an LLM and get a response",
      "allowed": true,
      "schema": {
        "type": "object",
        "properties": {
          "messages": {
            "type": "array",
            "description": "Conversation messages"
          },
          "model": {
            "type": "string",
            "description": "Model to use"
          },
          "temperature": {
            "type": "number",
            "description": "Sampling temperature"
          }
        },
        "required": ["messages"]
      }
    },
    {
      "name": "retrieval/search",
      "category": "retrieval",
      "description": "Search the knowledge base",
      "allowed": true,
      "schema": {
        "type": "object",
        "properties": {
          "query": {"type": "string"},
          "limit": {"type": "integer"},
          "collection": {"type": "string"}
        },
        "required": ["query"]
      }
    },
    {
      "name": "voice/transcribe",
      "category": "voice",
      "description": "Transcribe audio to text",
      "allowed": false,
      "reason": "Not in agent tool permissions"
    }
  ],
  "categories": {
    "llm": 3,
    "retrieval": 3,
    "voice": 0,
    "document": 0
  }
}

Use Cases

Pre-Flight Check

Before executing a task, verify capabilities:

def can_perform_task(client, required_tools, required_models):
    # Check identity
    whoami = client.call_tool("self_inspect/whoami", {})

    # Verify tools
    missing_tools = [t for t in required_tools if t not in whoami["permissions"]["tools"]]
    if missing_tools:
        return False, f"Missing tools: {missing_tools}"

    # Verify models
    missing_models = [m for m in required_models if m not in whoami["permissions"]["models"]]
    if missing_models:
        return False, f"Missing models: {missing_models}"

    # Check budget
    usage = client.call_tool("self_inspect/get_my_usage", {})
    if usage["daily"]["remaining_budget"] < 1.00:
        return False, "Insufficient daily budget"

    return True, "Ready"

# Usage
can_do, reason = can_perform_task(
    client,
    required_tools=["llm/chat", "retrieval/search"],
    required_models=["gpt-5.2"]
)
print(f"Can perform task: {can_do} - {reason}")

Budget Monitoring

def check_budget_status(client):
    usage = client.call_tool("self_inspect/get_my_usage", {})

    session_pct = usage["session"]["cost"] / usage["limits"]["cost_per_session"]
    daily_pct = usage["daily"]["cost"] / usage["limits"]["cost_daily"]

    if session_pct > 0.8:
        print(f"WARNING: Session budget {session_pct:.0%} used")
    if daily_pct > 0.8:
        print(f"WARNING: Daily budget {daily_pct:.0%} used")

    return usage

Dynamic Tool Discovery

def get_available_search_tools(client):
    tools = client.call_tool(
        "self_inspect/list_my_tools",
        {"category": "retrieval"}
    )

    available = [t["name"] for t in tools["tools"] if t["allowed"]]
    return available

# Use the best available search method
search_tools = get_available_search_tools(client)
if "retrieval/search_and_rerank" in search_tools:
    # Use combined search
    pass
elif "retrieval/search" in search_tools:
    # Use basic search
    pass

Best Practices

1. Check permissions first - Verify capabilities before attempting tasks
2. Monitor usage - Regularly check budget status
3. Handle gracefully - Degrade functionality based on available tools
4. Log warnings - Track when approaching limits
5. Cache identity - whoami results rarely change during a session

Next Steps

• Agent Profiles - Configure agent settings
• Cost Transparency - Detailed cost tracking
• Permissions - Permission model