{
  "uid": "cogitave.learn.native-mcp-interface.tools-and-resources",
  "kind": "moduleUnit",
  "href": "/modules/native-mcp-interface/tools-and-resources/",
  "title": "Tools, resources, and propose-only governance",
  "summary": "",
  "type": null,
  "products": [],
  "roles": [],
  "levels": [],
  "subjects": [],
  "headings": [
    "The tools",
    "Resources",
    "Reads are open, writes only propose"
  ],
  "source": "## The tools\n\n[mcp-interface.md §2](../../../../core/docs/mcp-interface.md#2-tools) defines\neight query tools plus five request-lifecycle tools (two of them propose-only\nwrites), all declaring both an `inputSchema` and an `outputSchema` and returning\nstructured content alongside a text rendering:\n\n| Tool | Purpose |\n| --- | --- |\n| `docs_search` | Hybrid retrieval (BM25 + vector + graph rerank) over Doc/Article/Unit/Module/LearningPath/ADR nodes. |\n| `docs_fetch` | Fetch a node's full canonical content by UID - a catalog read. |\n| `code_sample_search` | Search compile-checked `:::code` samples across the corpus. |\n| `get_related` | Typed-edge neighborhood of a node - `partOf`, `dependsOn`, `xref`, and the rest of the closed edge vocabulary. |\n| `get_learning_path` | Prerequisite-ordered Units/Skills toward a target competency - the same traversal that ordered this very path. |\n| `resolve_xref` | Resolve an `@uid` / `<xref:uid>` to its current URI and title, moniker-aware. |\n| `query_graph` | A bounded, read-only property-graph query over the closed node/edge vocabulary. |\n| `describe_schema` | Returns the closed vocabulary itself - node labels, typed edges, required attributes, monikers. |\n\n`describe_schema` is worth a second look: it is documented as the **first call\nin agent onboarding**, because an agent that already knows the vocabulary can\nplan a multi-hop query instead of dumping the estate just to find its footing.\n\n`query_graph` is the one tool that could become a general escape hatch, so it\nis deliberately fenced by the **bounded graph-query profile**: read-only (no\nmutation or DDL), an allowlisted set of node/edge labels, a capped traversal\ndepth (`*1..4`), a hard row cap (`limit` ≤ 1000, with a `truncated` flag), a\nper-query timeout, and a guard against traversal blow-ups. A violation of any\nbound returns a tool error rather than a silently truncated result.\n\n## Resources\n\nEvery node in the graph is also addressable directly, as an MCP **resource**,\non the URI template `cogitave://{type}/{id}` - for example\n`cogitave://doc/cogitave.core.architecture` or\n`cogitave://request/req-2026-0042`. `resources/templates/list` advertises that\ntemplate with per-type title, description, `mimeType`, and an icon;\n`resources/list` paginates the catalog with `type`/`product` filters;\n`resources/read` returns the node payload plus a `contentHash` and\n`lastModified`. You can `resources/subscribe` to one node or to a whole\n`cogitave://{type}/` collection, and on a content change the server pushes\n`notifications/resources/updated` (and `list_changed` when the resource set\nitself changes) - the live-invalidation ADR-0003 promised over polling.\n\n## Reads are open, writes only propose\n\nThe request-lifecycle tools - `list_requests`, `get_request`, `get_dod`,\n`request_intake`, `advance_stage` - bind the same\n[request lifecycle](../../../../agents/lifecycle/LIFECYCLE.md) a human works to\nthis MCP surface. Reads are unrestricted within a caller's grant, but\n`request_intake` and `advance_stage` are **propose-only**: they validate an\nintake form or a stage transition, open the corresponding GitHub issue or PR,\nand stage a **draft** `Request` node - they never mutate protected state or\napply anything, honoring AGENTS.md's \"no unapproved mutation.\"\n",
  "partOf": "cogitave.learn.native-mcp-interface",
  "durationInMinutes": 7,
  "quiz": null
}