`aws_narrative_refs`

Fetch narrative documentation and reference links for an AWS topic.

Returns the long-form narrative chunks — patterns, trade-offs, how-tos — curated for an AWS topic. Use this when you need the "why and when" behind an architectural choice, not just the primitive reference. Topics are free-form strings (e.g. vpc-peering, iam-roles, multi-region-failover); the backend resolves them against its narrative index.

Family: knowledge
Source: cbx-mcp/src/cbx_mcp/tools/knowledge.py::aws_narrative_refs
Backend: GET /v1/knowledge/aws/narrative?topic={topic}

Input schema

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "description": "Free-form topic identifier, e.g. 'vpc-peering', 'iam-roles', 'multi-region-failover'."
    }
  },
  "required": ["topic"]
}

Unknown topics return an empty chunks list rather than an error, which is convenient for speculative lookups but means callers should treat an empty response as "no narrative on file" rather than "failure".

Output schema

On success the tool returns the backend's PublicKnowledgeResponse wrapped in the standard MCP envelope:

{
  "type": "object",
  "properties": {
    "isError": { "type": "boolean" },
    "result": {
      "type": "object",
      "properties": {
        "kb_version": { "type": "integer" },
        "chunks": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "doc_path":    { "type": "string" },
              "heading":     { "type": ["string", "null"] },
              "chunk_text":  { "type": "string" },
              "chunk_index": { "type": "integer" },
              "token_count": { "type": "integer" },
              "category":    { "type": "string" },
              "type_ids":    { "type": "array", "items": { "type": "string" } },
              "tags":        { "type": "array", "items": { "type": "string" } }
            },
            "required": [
              "doc_path",
              "chunk_text",
              "chunk_index",
              "token_count",
              "category"
            ]
          }
        }
      },
      "required": ["kb_version"]
    },
    "error": { "type": "string" }
  },
  "required": ["isError"]
}

Chunks for this tool tend to land in the narrative and howto categories. doc_path points back into the curated knowledge base, which is useful when wiring tool output into a citation pipeline.

Example call

{
  "name": "aws_narrative_refs",
  "arguments": {
    "topic": "vpc-peering"
  }
}

Example result

Illustrative — real responses contain several chunks covering narrative, trade-offs, and step-by-step how-tos.

{
  "isError": false,
  "result": {
    "kb_version": 12,
    "chunks": [
      {
        "doc_path": "resources/aws/narrative/networking/vpc_peering.md",
        "heading": "VPC peering: when and why",
        "chunk_text": "VPC peering is the cheapest way to give two VPCs private connectivity, but it doesn't transit...",
        "chunk_index": 0,
        "token_count": 196,
        "category": "narrative",
        "type_ids": ["aws:ec2/vpc@v1", "aws:ec2/vpc_peering_connection@v1"],
        "tags": ["networking", "vpc", "connectivity"]
      }
    ]
  }
}