Context-aware MCP tool descriptions

[jfrench9]

Summary

MCP tool descriptions are static strings that never change regardless of which graph the user is connected to. This spec proposes a ToolContext system that enriches tool descriptions based on the connected graph's manifest and schema — making tools aware of shared repository context (SEC, sibling subgraphs), schema patterns (RoboLedger financial schema), and graph-specific guidance. Configuration lives in adapter manifests (adapters/sec/manifest.py) and schema extensions (schemas/extensions/roboledger.py).

Status

Draft

Problem Statement: Current State

Tool descriptions are hardcoded strings in get_tool_definition() on each tool class (middleware/mcp/tools/*.py). The only context-awareness today is:

• describe-graph-structure has a hardcoded if self.client.graph_id in ("sec", "sec_historical") branch
• get-example-queries has a hardcoded if self.client.graph_id == "sec" branch
• _should_include_element_discovery() checks the manifest's has_element_discovery flag

Every other tool serves identical description text regardless of graph. This causes three problems:

1. Discoverability — sec_historical exists as a sibling subgraph but no tool description mentions it. An agent will never discover it unless they call list-workspaces.
2. Schema mismatch — Tool descriptions reference SEC/XBRL patterns even for graphs with completely different schemas.
3. Wasted context window — SEC-specific guidance (dimensional facts, period types) is served to every graph, wasting tokens.

Problem Statement: Desired State

Tool descriptions adapt to graph context:

• SEC graph: mentions sec_historical sibling, includes dimensional fact warnings, period type guidance
• User graph with RoboLedger schema: references actual node types and relationships, omits SEC-specific cruft
• Custom user graph: gets clean generic descriptions with no financial schema references

Configuration is centralized:

• Shared repository MCP config lives in the adapter manifest (alongside billing, rate limits, endpoints)
• Schema-derived guidance lives in schema extension modules (alongside schema definitions)
• No hardcoded graph_id checks in tool classes

Problem Statement: Why Now?

v1.4.0 marks the platform maturation milestone. As we add more shared repositories and schema extensions, hardcoding if graph_id == "sec" branches doesn't scale. The sec_historical subgraph is already invisible to agents — this will only get worse as we add more subgraphs and shared repos.

Proposed Solution: Approach

Three new concepts:

1. MCPToolConfig — added to SharedRepositoryManifest in adapters/base.py. Contains tool_supplements (dict of tool_name → additional description text), sibling_subgraphs, and display_name.

2. MCP_GUIDANCE — a constant exported from schema extension modules (schemas/extensions/roboledger.py). Co-locates schema knowledge with the schema definition.

3. ToolContext — built at init time in GraphMCPTools from manifest + schema. Passed to each tool's get_tool_definition() to enrich descriptions.

Key design principle: append, not replace. Base descriptions are always present. Context supplements are added on top. User graphs with no manifest get today's generic descriptions (zero regression).

Components Affected

• Middleware (/robosystems/middleware/)
• Configuration (/robosystems/config/)

Other directories touched but not architecturally affected:

• adapters/base.py — add MCPToolConfig dataclass
• adapters/sec/manifest.py — add mcp_config field
• schemas/extensions/roboledger.py — add MCP_GUIDANCE constant

Key Changes

middleware/mcp/tools/context.py        — NEW: ToolContext dataclass
adapters/base.py                       — Add MCPToolConfig, add mcp_config to SharedRepositoryManifest
adapters/sec/manifest.py               — Add mcp_config with tool supplements + sibling subgraphs
middleware/mcp/tools/base_tool.py      — Update get_tool_definition() to accept ToolContext
middleware/mcp/tools/manager.py        — Build ToolContext in __init__, pass to tools
middleware/mcp/tools/structure_tool.py  — Remove hardcoded SEC branches (Phase 4)
middleware/mcp/tools/example_queries_tool.py — Remove hardcoded SEC branches (Phase 4)
middleware/mcp/tools/constants.py      — Move schema-specific constants to schema guidance (Phase 4)
schemas/extensions/roboledger.py       — Add MCP_GUIDANCE constant
middleware/mcp/tools/cypher_tool.py    — Trim generic base description

Data Model Changes

No database schema changes. MCPToolConfig is a frozen dataclass on the manifest (in-memory config).

API Changes

No API contract changes. The /v1/graphs/{graph_id}/mcp/tools endpoint returns the same response shape — tool definitions with name, description, inputSchema. Only the description content changes based on graph context.

Implementation Plan

• Phase 1: ToolContext and Manifest Config

  • Create middleware/mcp/tools/context.py with ToolContext dataclass
  • Add MCPToolConfig to adapters/base.py
  • Add mcp_config to SEC manifest
  • Build ToolContext in GraphMCPTools.__init__
  • Pass context to get_tool_definition()

• Phase 2: Tool Description Enrichment

  • Update BaseTool.get_tool_definition() signature
  • Update each tool class to append context supplements
  • Verify enrichment works for SEC, sec_historical, and user graphs

• Phase 3: Schema-Derived Guidance

  • Add MCP_GUIDANCE to schemas/extensions/roboledger.py
  • Build schema guidance resolution in context builder
  • Append schema guidance to schema-aware tools

• Phase 4: Remove Hardcoded SEC Logic

  • Remove if graph_id == "sec" branches from tool classes
  • Move PERIOD_TYPE_GUIDANCE and DIMENSIONAL_FACTS_WARNING to schema guidance
  • Keep QUERY_PATTERN_GUIDANCE as shared constant (LadybugDB-specific, not schema-specific)

Dependencies: None — this is self-contained within the MCP tool layer.

Testing

• Unit tests: ToolContext construction from manifest with/without mcp_config
• Unit tests: Tool description enrichment appends correctly
• Unit tests: Graceful degradation when context is None
• Unit tests: Schema guidance resolution from extension modules
• Integration tests: SEC graph returns enriched descriptions
• Integration tests: sec_historical returns sibling reference to sec
• Integration tests: User graph returns base descriptions without SEC content

Rollout

Environments: Development → Staging → Production

No feature flags needed — this only changes tool description text, not behavior. Descriptions are generated at tool-list time, so changes take effect immediately on deploy.

Rollback plan: Revert the PR. Tool descriptions go back to static strings.

Success Criteria

• An AI agent connecting to sec sees sec_historical mentioned in tool descriptions without calling list-workspaces
• An AI agent connecting to a user graph does NOT see SEC-specific guidance (dimensional facts, period types)
• Zero hardcoded if graph_id == "sec" checks remain in tool classes
• SEC-specific schema knowledge lives in adapters/sec/manifest.py and schemas/extensions/roboledger.py, not in tool files
• Adding a new shared repo's MCP context requires only manifest config, no tool code changes

Open Questions

• Should example queries also come from the manifest? Currently hardcoded in example_queries_tool.py for SEC. Could move to tool_supplements or a dedicated example_queries field on MCPToolConfig.
• Token budget — how much supplementary description text is too much for agent context windows?
• Should get-graph-info (handler-level, not a tool) also return manifest-enriched metadata (display name, available subgraphs)?

References

• Spec: local/docs/specs/context-aware-mcp-tools.md
• Current tool implementations: robosystems/middleware/mcp/tools/
• SEC manifest: robosystems/adapters/sec/manifest.py
• Schema extensions: robosystems/schemas/extensions/
• Shared repository registry: robosystems/config/shared_repositories.py

[jfrench9]

Update: Context-Aware Tool Availability (Beyond Descriptions)

Updated the local spec (local/docs/specs/context-aware-mcp-tools.md) with a new section on curated, context-specific tools — extending the vision beyond just context-aware descriptions.

The Insight

While testing the SEC entity update fix in production, we ran an end-to-end financial analysis on AAP (Advance Auto Parts) using the MCP tools. The experience surfaced concrete friction points that context-aware descriptions alone won't solve:

• Fact deduplication: Got 4+ copies of the same us-gaap:Assets for the same period (10-K restating prior 10-Q values). Had to manually reason through which value was authoritative.
• Unit/scale inconsistency: AAP's FY2025 10-K reports in millions while prior filings used thousands. No metadata surfaced to disambiguate.
• Element ambiguity: Two us-gaap:NetIncomeLoss values for the same period — one from continuing operations, one total including discontinued ops. Required contextual reasoning.
• Multiple queries needed: Building a basic financial summary required 3-4 Cypher queries plus manual synthesis.

These are SEC/XBRL-specific data quality problems. A QuickBooks-synced RoboLedger graph with qb: tagged elements has none of them — it has different problems (trial balance computation, transaction drill-down).

What Was Added to the Spec

SEC-specific curated tools (would live in adapters/sec/mcp_tools/):

• get-company-financials — Clean financial summary handling deduplication, unit normalization, period alignment
• compare-companies — Multi-ticker normalized comparison tables
• screen-filings — Find filings by SIC code, industry, form type, date range
• find-peers — Discover comparable companies by SIC + revenue scale
• get-filing-sections — Text block retrieval (when available)

RoboLedger user graph tools (future, for qb: tagged data):

• get-trial-balance, get-income-statement, get-balance-sheet, get-transaction-detail

RoboInvestor tools (future):

• get-portfolio-summary, get-position-history, get-security-price

Architecture Fit

The ToolContext from Phases 1-4 supports this naturally. MCPToolConfig gets a custom_tools field that registers additional tool classes per context. GraphMCPTools instantiates base tools + custom tools and returns the combined set. No MCP protocol or API changes needed.

New Open Questions Added

4. Where should SEC-specific tools live? (adapters/sec/mcp_tools/ vs middleware/mcp/tools/sec/)
5. Should curated tools use raw Cypher or a reusable financial data access layer?
6. MarketData integration — RoboInvestorContext schema split to add Security/MarketData/Dividend nodes to SEC shared repo for price data, enabling AI-computed valuation ratios per-query