Skip to content

docs(api-surfaces): document missing MCP tools (write, evolve, insights, tune) - #570

Open
Souptik96 wants to merge 1 commit into
caura-ai:mainfrom
Souptik96:docs/api-surfaces-missing-mcp-tools-550
Open

docs(api-surfaces): document missing MCP tools (write, evolve, insights, tune)#570
Souptik96 wants to merge 1 commit into
caura-ai:mainfrom
Souptik96:docs/api-surfaces-missing-mcp-tools-550

Conversation

@Souptik96

Copy link
Copy Markdown

Summary

docs/api-surfaces.md was out of sync with the MCP tool surface registered in
core-api/src/core_api/mcp_server.py. The charter named only 8 of the 12
registered MCP tools, so a reader inventorying the API surface from the doc
concluded there was no write, outcome-reporting, insights, or tuning tool —
while the server registers and serves all four.

This documents the four missing tools and gives the whole MCP surface a
first-class, per-tool reference.

Changes

  • Add a new ## MCP tool surface section: a table of all 12 registered
    MCP tools with Transport(s), Trust required, and a one-line Contract,
    matching the issue's requested shape. Values are sourced from the ToolSpec
    single-source-of-truth in core-api/src/core_api/tools/*.py and the handlers
    in core_api/mcp_server.py.
  • Name memclaw_write (bulk write) and memclaw_tune (per-agent search
    profile) in the existing Surface ownership table.
  • Add the previously-absent Karpathy Loop concerns to the ownership table:
    Outcome reporting / weight reinforcement (memclaw_evolve) and
    Reflection / insights (memclaw_insights).

The four previously-undocumented tools

Tool Trust Contract
memclaw_write 0 (needs write capability) Primary write path — single or batch (≤100).
memclaw_evolve ≥1 (agent), ≥2 (fleet/all) Outcome reporting / weight reinforcement.
memclaw_insights ≥1 (agent), ≥2 (fleet/all) Reflection (contradictions, failures, stale, divergence, patterns, discover).
memclaw_tune 0 (needs write capability) Persistent recall-profile tuning.

Verification

  • Cross-checked every row against the handler definitions in mcp_server.py
    and the ToolSpec declarations (trust levels, plugin_exposed,
    op/scope-specific floors).
  • Confirmed REST counterparts exist for each tool (entities.py, agents.py,
    evolve.py, insights.py, stats.py, documents.py, keystones.py,
    memories.py).
  • Docs-only change; no code paths touched.

Closes #550

docs/api-surfaces.md named only 8 of the 12 registered MCP tools, so a reader inventorying the surface concluded there was no write, outcome-reporting, insights, or tuning tool.

Add an 'MCP tool surface' table covering all 12 registered tools with their transport(s), minimum trust level, and a one-line contract, sourced from the ToolSpec SoT in core-api/src/core_api/tools/*.py and the handlers in core_api/mcp_server.py. Also name memclaw_write and memclaw_tune in the ownership table and add the previously-absent Karpathy Loop concerns (memclaw_evolve, memclaw_insights).

Closes caura-ai#550
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(api-surfaces): document missing MCP tools (memclaw_write, memclaw_evolve, memclaw_insights, memclaw_tune)

1 participant