AI-Native Financial Data Foundation (31) – Tool Contracts: Making Agent Capabilities Explicit – Data Ninjago (Financial Data Architecture)

In the previous article, I explored a retrieval pattern for the financial semantic layer.

The pattern is:

			
user question
→ classify intent and extract context
→ scoped hybrid candidate search
→ entity resolution
→ constrained graph traversal
→ governed evidence
→ LLM explanation

		

For governed financial semantic questions, the LLM should not freely inspect the graph, invent queries, or decide truth from its own internal knowledge. The graph should provide evidence. The LLM should interpret the question, choose the right retrieval path, and explain the evidence.

This leads naturally to the next question:

How should these retrieval capabilities be exposed to an AI agent?

One possible answer is tool contracts. A tool contract makes an agent capability explicit. It defines what the agent can ask for, what input is required, what graph retrieval pattern will be used, what evidence will be returned, and what the LLM is allowed to say based on that evidence.

From retrieval patterns to tool contracts

In the previous article, I discussed reusable retrieval patterns such as:

			
concept lookup
readiness assessment
alternative source discovery
mapping blocker analysis
evidence-path explanation

		

A tool contract turns these patterns into explicit agent capabilities. The agent does not need to generate arbitrary Cypher.

It can call:

assess_readiness(dataset_hint, use_case_hint)

and receive structured governed evidence.

This is a different way of thinking about GraphRAG. The graph is not just a source of context. It becomes a governed capability layer.

Example tool contract: readiness assessment

Consider the question:

Can this broker feed support IRS valuation?

A possible tool contract may look like this:

			
{
  "name": "assess_readiness",
  "description": "Assess whether a dataset provides...",
  "input_schema": {
    "dataset_hint": "string",
    "use_case_hint": "string",
    "product_type_hint": "string | null"
  },
  "output_schema": {
    "answer_type": "readiness_assessment",
    "dataset": "string",
    "use_case": "string",
    "overall_status": "ready | not_ready | partial | unknown",
    "present_approved": "SemanticConcept[]",
    "present_requires_review": "MappingEvidence[]",
    "missing": "SemanticConcept[]",
    "alternative_sources": "AlternativeSourceEvidence[]",
    "evidence_paths": "EvidencePath[]",
    "answer_policy": "AnswerPolicy"
  },
  "failure_modes": [
    "dataset_not_resolved",
    "use_case_not_resolved",
    "no_required_concepts",
    "no_mappings_found",
    "ambiguous_dataset",
    "ambiguous_use_case"
  ]
}

		

The contract tells the agent what this tool is for. It is not a general graph query tool. It is a readiness-assessment capability. The underlying graph traversal may be:

			
use case
→ required concepts
→ compare with concepts provided by dataset
→ classify present / missing / requires review
→ attach validation and source evidence

		

The agent does not need to build this traversal itself. It is already provided by the tool.

The tool may return:

			
{
  "answer_type": "readiness_assessment",
  "dataset": "Broker A IRS Filled Trades",
  "use_case": "IRS Valuation Readiness",
  "overall_status": "not_ready",
  "present_approved": [
    "TradeIdentifier",
    "ProductType",
    "NotionalAmount",
    "Currency",
    "EffectiveDate",
    "MaturityDate",
    "Counterparty"
  ],
  "present_requires_review": [
    {
      "concept": "FixedRate",
      "source_field": "fixed_rate",
      "confidence": 0.88,
      "review_status": "requires_sme_review"
    },
    {
      "concept": "FloatingRateIndex",
      "source_field": "float_index",
      "confidence": 0.84,
      "review_status": "requires_sme_review"
    }
  ],
  "missing": [
    "DayCountConvention",
    "BusinessDayConvention"
  ],
  "alternative_sources": [
    {
      "missing_concept": "DayCountConvention",
      "source_system": "Internal Terms Master",
      "dataset": "IRS Terms Master",
      "field": "day_count_convention"
    }
  ],
  "answer_policy": {
    "allowed_claim": "not_ready",
    "must_flag_review_items": true,
    "must_list_missing_concepts": true,
    "must_suggest_alternatives": true,
    "allow_speculation": false,
    "confidence_floor": 0.70
  }
}

		

This output gives the LLM enough information to explain the result, but it also constrains the explanation.

Example tool contract: concept lookup

Now consider a narrower question:

Do we have the fixed coupon needed for valuation?

The user says “fixed coupon”, but the graph may store FixedRate. The agent needs a tool that can resolve business language to a semantic concept and then retrieve evidence about that concept.

A possible tool contract:

			
{
  "name": "lookup_concept_evidence",
  "description": "Resolve a business term or source..."
  "input_schema": {
    "term": "string",
    "dataset_hint": "string | null",
    "use_case_hint": "string | null",
    "product_type_hint": "string | null"
  },
  "output_schema": {
    "answer_type": "concept_lookup",
    "resolution_status": "resolved | ambiguous | not_found",
    "resolved_concept": "SemanticConcept | null",
    "source_fields": "SourceField[]",
    "use_cases": "UseCase[]",
    "validation_rules": "ValidationRule[]",
    "mapping_evidence": "MappingEvidence[]",
    "evidence_paths": "EvidencePath[]",
    "answer_policy": "AnswerPolicy"
  },
  "failure_modes": [
    "no_candidates",
    "ambiguous_concept",
    "no_evidence_path",
    "mapping_requires_review"
  ]
}

		

For the fixed coupon question, the tool may return:

			
{
  "answer_type": "concept_lookup",
  "resolution_status": "resolved",
  "resolved_concept": {
    "concept_id": "FixedRate",
    "name": "FixedRate"
  },
  "source_fields": [
    {
      "dataset": "Broker A IRS Filled Trades",
      "field": "fixed_rate",
      "sample_value": "0.0425"
    }
  ],
  "mapping_evidence": [
    {
      "source_field": "fixed_rate",
      "semantic_concept": "FixedRate",
      "confidence": 0.88,
      "review_status": "requires_sme_review"
    }
  ],
  "validation_rules": [
    "FixedRateMustBePresent"
  ],
  "evidence_paths": [
    [
      "Broker A IRS Filled Trades",
      "fixed_rate",
      "FixedRate",
      "IRS Valuation Readiness",
      "FixedRateMustBePresent"
    ]
  ],
  "answer_policy": {
    "allowed_claim": "partial",
    "must_flag_review_items": true,
    "allow_speculation": false,
    "confidence_floor": 0.70
  }
}

		

The final explanation can then say:

The feed appears to provide the fixed coupon through fixed_rate, which maps to FixedRate. FixedRate is required for IRS Valuation Readiness and is checked by FixedRateMustBePresent. However, the mapping still requires SME review, so it should not be treated as fully confirmed yet.

Again, the LLM is not inventing the answer. It is explaining the governed evidence returned by the tool.

Example tool contract: alternative source discovery

Another common question is:

Where can I find the day count convention?

This should not require the LLM to search documents randomly. The graph should expose a tool for alternative source discovery.

			
{
  "name": "find_alternative_sources",
  "description": "Find source fields, datasets,...",
  "input_schema": {
    "concept_term": "string",
    "product_type_hint": "string | null",
    "use_case_hint": "string | null"
  },
  "output_schema": {
    "answer_type": "alternative_source",
    "resolution_status": "resolved | ambiguous | not_found",
    "resolved_concept": "SemanticConcept | null",
    "sources": "AlternativeSourceEvidence[]",
    "evidence_paths": "EvidencePath[]",
    "answer_policy": "AnswerPolicy"
  },
  "failure_modes": [
    "no_candidates",
    "ambiguous_concept",
    "no_alternative_source"
  ]
}

		

A possible result:

			
{
  "answer_type": "alternative_source",
  "resolution_status": "resolved",
  "resolved_concept": {
    "concept_id": "DayCountConvention",
    "name": "DayCountConvention"
  },
  "sources": [
    {
      "source_system": "Internal Terms Master",
      "dataset": "IRS Terms Master",
      "field": "day_count_convention",
      "confidence": 0.95,
      "review_status": "approved"
    }
  ],
  "evidence_paths": [
    [
      "DayCountConvention",
      "day_count_convention",
      "IRS Terms Master",
      "Internal Terms Master"
    ]
  ],
  "answer_policy": {
    "allowed_claim": "source_found",
    "allow_speculation": false,
    "must_use_verified_sources_only": true
  }
}

		

The LLM can explain:

DayCountConvention can be sourced from IRS Terms Master through the field day_count_convention.
This dataset is provided by Internal Terms Master. The graph marks this source as approved.

If no source is found, the tool should say that explicitly. It should not ask the LLM to guess.

Failure is part of the contract

A tool contract should not only define successful output. It should also define failure output. This matters because failure is common in semantic retrieval. The user may use a term that has not been onboarded. The graph may contain several similar concepts. The concept may exist, but no evidence path may connect it to the current use case. A concept may be missing, and no alternative source may be available.

These cases need explicit handling.

For example:

			
{
  "answer_type": "alternative_source",
  "resolution_status": "resolved",
  "resolved_concept": {
    "concept_id": "BusinessDayConvention",
    "name": "BusinessDayConvention"
  },
  "sources": [],
  "failure_status": "no_alternative_source",
  "answer_policy": {
    "allowed_claim": "no_verified_source_found",
    "allow_speculation": false,
    "must_acknowledge_gap": true
  }
}

		

The answer should be:

BusinessDayConvention is a required concept, but the graph does not currently show a verified alternative source for it.

It should not be:

You can probably find it in the terms master.

That may be true in many institutions, but if the graph has not provided the evidence, the agent should not claim it.

Tool contracts reduce agent risk

Tool contracts reduce several types of risk.

First, they reduce query risk. The agent does not need to generate arbitrary Cypher for common governed tasks.
Second, they reduce schema risk. The agent does not need to remember graph labels, relationship names, or property names.
Third, they reduce governance risk. The tool output carries review status, confidence, and answer policy.
Fourth, they reduce explanation risk. The LLM receives structured evidence and clear answer boundaries.
Fifth, they make testing easier. A tool can be tested with known inputs and expected outputs.

This is why tool contracts are more than a software convenience. They are a governance mechanism.

Tool contracts are smaller than user questions

At first, it may seem that many tool contracts will be needed because users can ask many different questions. But the number of user-facing questions can grow much faster than the number of underlying retrieval capabilities.

For example, all these questions may reuse the same assess_readiness tool:

			
Can this broker feed support IRS valuation?
What is missing for valuation?
Which concepts are present?
Which fields block readiness?
Which mappings require SME review?

		

All these questions may reuse the same find_alternative_sources tool:

			
Where can I find day count convention?
Which system has the day count?
Is there another source for this missing concept?

And all these questions may reuse the same lookup_concept_evidence tool:

			
Do we have fixed coupon?
Why is fixed_rate required?
Which rule depends on FixedRate?
Which dataset provides FixedRate?

The tool catalog does not need to grow one-to-one with user questions. It grows with reusable semantic capabilities. This is what makes the pattern manageable.

The work is not about writing endless one-off prompts. The work is about turning financial semantics into governed assets and exposing them through reusable tools.

Tool contracts and answer policy

The most important part of the contract may be the answer_policy. This field controls how the LLM should explain the result.

For example:

			
{
  "answer_policy": {
    "allowed_claim": "partial",
    "must_flag_review_items": true,
    "must_list_missing_concepts": false,
    "must_suggest_alternatives": false,
    "allow_speculation": false,
    "confidence_floor": 0.70
  }
}

		

This tells the LLM that the answer is partial, not fully confirmed. It also says that review-required mappings must be flagged. This turns governance metadata into behaviour. Without this, governance information may appear in the data but disappear from the final answer. That would defeat the purpose of the semantic layer.

Why tool contracts matter for AI-native financial data

In traditional data platforms, a user may read documentation, check mappings, inspect tables, ask SMEs, and manually decide whether a dataset is usable.

In an AI-native financial data foundation, agents may perform some of this reasoning on behalf of users. That makes the capability boundary extremely important. The agent should not have vague access to everything. It should have explicit capabilities. Each capability should have clear semantics, controlled graph traversal, structured output, and governance-aware explanation.

This is especially important in financial data because many answers are not simply true or false.

They may be:

			
present but not approved
mapped but low confidence
available but from a non-authoritative source
missing from the feed but available elsewhere
valid for valuation but not for reporting
ready for one use case but not another

		

Tool contracts help preserve these distinctions. They make the agent less like a chatbot and more like a governed semantic assistant.

*AI-Native Financial Data Foundation