finos-mcp
This server is a read-only MCP interface to the FINOS AI Governance Framework (AIGF), letting agents safely explore, search, and cross-reference AI governance risks and controls.
List and retrieve AIGF risks (by AIR-* id, short id, or title) with summaries, status, mitigations, and related risks.
List and retrieve AIGF controls/mitigations (by AIR-PREV/DET id, short id, or title) with crosswalk references.
Map risks to controls by explicit ids, free-text queries, or multiple queries; see coverage and uncovered risks.
Crosswalk controls to external frameworks: NIST SP 800-53, ISO 42001, EU AI Act, OWASP, and more.
Full-text search over risks and controls with citations, plus inspect whether search is lexical or hybrid.
Reverse lookup: find AIGF items citing a given external reference (e.g. NIST, OWASP, EU AI Act keys).
List reference frameworks and their usage counts; get server info, provenance, counts, and policy.
All operations are read-only, rate-limited, input-capped, and audited, with no runtime network calls by default.
Provides crosswalk mappings between AIGF risks and controls and OWASP frameworks such as the LLM Top 10, enabling users to find AIGF items by OWASP reference keys and map controls to OWASP standards.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@finos-mcpFind AIGF risks and controls related to model bias"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
finos-mcp
Every badge above reads the numbers CI publishes to the metrics branch on each push to main, so they resolve to a specific commit rather than a claim.
Typed, read-only MCP servers for FINOS data standards, so any agent can query them safely:
Server | Standard | What it exposes |
| Risks and controls with their public | |
| Type descriptions, product and payout catalogue, event qualification, and validation of CDM JSON objects (Rune and legacy formats) | |
| Intents, context-type schemas, context validation, intent suggestion for a given context |
All three share finos-mcp-core, which is where the safety guarantees live.
See docs/demo.md for a real transcript: five tool calls across the three
servers, including CDM catching three planted defects in a Rune-format BusinessEvent and
reporting each one's path in the submitted document.
Safety model
These servers are read-only. They contain no tool that writes to, posts to, or mutates any external system, file, or network endpoint. All framework content and schemas are vendored into the packages at build time with recorded upstream commit hashes (SOURCE.json in each _vendor/ directory); the servers make no network calls at runtime. Every tool call is rate-limited per tool, input-capped, and written to an audit log. Any failure is returned as a structured error the calling agent can act on.
Concretely, finos-mcp-core enforces:
Read-only, no override. A tool can only be registered with
readOnlyHint: true; the server refuses to servetools/*if any tool lacks it.Rate limits. Token bucket per client and tool; exhaustion is a JSON-RPC error (
-32029,rate_limited) withretry_after_s.Size caps. Serialised arguments above the cap (64 KiB by default; 1 MiB for CDM validation) are rejected before the tool runs with a structured
input_too_largeresult; oversized results are replaced withoutput_too_largeand a hint to narrow the request.Structured errors.
not_found,ambiguous_id(with candidates),invalid_input,validation_failed,unsupported_format: JSON the model can parse and recover from.Audit log. One JSON line per request to stderr or
FINOS_MCP_AUDIT_PATH, with the tool name, a sha256 of the arguments (never the raw arguments unlessFINOS_MCP_AUDIT_RAW_ARGS=1), outcome and duration.
Policy can only be tightened from the environment (FINOS_MCP_MAX_INPUT_BYTES, FINOS_MCP_RATE_CALLS, FINOS_MCP_RATE_WINDOW_S, FINOS_MCP_RATE_BURST).
The default install is lexical-only and makes no network calls: search_framework is plain BM25 with a fuzzy title boost. Installing the optional semantic extra (finos-mcp-core[semantic] / finos-mcp-aigf[semantic], pulling in model2vec) enables hybrid search — BM25 fused with a small (~15 MB, MIT-licensed) static-embedding model, minishlab/potion-base-4M by default — which downloads that model from Hugging Face on first use unless FINOS_MCP_EMBEDDING_MODEL points at a local copy. Loading the model never blocks correctness: any failure (extra not installed, no network, bad path) is caught and leaves the server in pure lexical mode. The active mode is visible via the search_status tool, and FINOS_MCP_SEARCH_MODE=lexical forces lexical-only explicitly regardless of what is installed.
Related MCP server: ibm-watsonx-gov-catalog-mcp-server
Run it
uv run finos-mcp-aigf # stdio, for Claude Desktop / Claude Code
uv run finos-mcp-aigf --transport streamable-http --port 8000Or as a container, which needs no writable filesystem and no capabilities:
docker run --rm -p 8000:8000 --read-only --cap-drop ALL ghcr.io/vardhjain/finos-mcp
docker run --rm -p 8000:8000 ghcr.io/vardhjain/finos-mcp \
finos-mcp-cdm --transport streamable-http --host 0.0.0.0 --port 8000See examples/ for Claude Desktop config, a LangGraph agent, and the demo.
Status
Released v0.1.2, on PyPI as
finos-mcp-core,
finos-mcp-aigf,
finos-mcp-cdm and
finos-mcp-fdc3 (Python 3.12+), and as a
multi-arch container. Documentation is published at https://vardhjain.github.io/finos-mcp/.
See PLAN.md for the design and the metrics CI publishes, and
RELEASING.md for how releases work.
Not affiliated with or endorsed by FINOS. These are independent, community packages. On
PyPI the finos- prefix is also used by official FINOS packages such as finos-cdm; nothing
here is one of them.
Development
uv sync --all-packages --all-extras
uv run pytest
uv run ruff check . && uv run mypy core/src servers/*/srcLicenses
Code is Apache-2.0. Vendored content keeps its upstream license: the AI Governance Framework is CC-BY-4.0; CDM and FDC3 materials are under the Community Specification License 1.0. See NOTICE.
Available Tools
11 toolsfind_by_external_referenceARead-onlyIdempotent
Reverse crosswalk: find the AIGF risks and controls that cite an external reference, e.g. key='sa-9' (NIST SP 800-53), 'llm01-2025' (OWASP LLM Top 10), 'c3-s2-a15' (EU AI Act), 'A-6-2-6' (ISO 42001). Matching is case-insensitive and ignores punctuation; optionally restrict to one framework name from list_reference_frameworks.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| framework | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| key | Yes | |
| matches | Yes | |
| framework | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations: matching is case-insensitive, ignores punctuation, and the framework filter is optional. This meaningfully helps an agent predict results without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then provides concrete examples and behavioral caveats. Every sentence adds value: the examples disambiguate key formats, and the matching rules prevent incorrect expectations. It is appropriately sized for a tool with two parameters and nuanced matching behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema already covers return shape, the description does not need to explain return values. It covers the tool's purpose, supported key formats, normalization behavior, optional framework restriction, and points to the authoritative list. For this complexity level, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema offers only generic titles ('Key', 'Framework') with 0% schema description coverage, so the description must carry the semantic burden. It fully compensates by explaining that 'key' is an external reference identifier with concrete examples and that 'framework' restricts results to a framework name from list_reference_frameworks. Both parameters are meaningfully clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Reverse crosswalk' and immediately states the exact resource ('AIGF risks and controls') and action ('find ... that cite an external reference'). The examples clarify the input format and the phrase 'reverse crosswalk' distinguishes it from mapping tools like map_control_to_external.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when you need to find risks/controls by an external reference. It also directs the user to list_reference_frameworks for valid framework names. However, it does not explicitly mention exclusions or contrast itself with search_framework or map_control_to_external, so it stops short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_controlARead-onlyIdempotent
Get one AIGF control by id (AIR-PREV-020, mi-20, 20, or its title), with the risks it mitigates, related controls, and crosswalk references (NIST SP 800-53, ISO 42001, ...). Set include_sections=false for a compact record.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| include_sections | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| type | Yes | |
| title | Yes | |
| status | Yes | |
| summary | Yes | |
| sections | No | |
| sequence | Yes | |
| short_id | Yes | |
| mitigates | No | |
| references | No | |
| type_label | Yes | |
| source_path | Yes | |
| citation_uri | Yes | |
| related_controls | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context about what the response contains (risks, related controls, crosswalk references) and that include_sections=false yields a compact record, which is meaningful beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, information-dense sentences. The main purpose and id formats are front-loaded, followed by the optional flag guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich annotations, an output schema, and only two parameters, the description covers everything an agent needs to select and invoke the tool correctly. It explains the lookup key, the response contents, and the compaction option.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates: it explains the id parameter with concrete accepted formats and explains the behavior of include_sections. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: get one AIGF control by id, and enumerates the included related data (risks, related controls, crosswalk references). The accepted id examples also help distinguish this from sibling list/map tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly implies use when retrieving a single control by id, and gives guidance on include_sections for compactness. However, it does not explicitly contrast with sibling tools like list_controls or find_by_external_reference, so the when-not-to-use context is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_riskARead-onlyIdempotent
Get one AIGF risk by id (AIR-SEC-010, ri-10, 10, or its title), with the controls that mitigate it, related risks, and external references. Set include_sections=false for a compact record without the full text.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| include_sections | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| type | Yes | |
| title | Yes | |
| status | Yes | |
| summary | Yes | |
| sections | No | |
| sequence | Yes | |
| short_id | Yes | |
| references | No | |
| type_label | Yes | |
| source_path | Yes | |
| citation_uri | Yes | |
| mitigated_by | No | |
| related_risks | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds useful behavioral context by explaining that the response includes mitigating controls, related risks, and external references, and that include_sections=false returns a compact record without full text.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the first covers the core action and output contents, the second covers the optional flag. No filler, and the most important usage detail is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich output schema present, annotations covering safety/idempotence, and clear explanation of id formats and the include_sections toggle, nothing essential is missing for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent (0% coverage), but the description compensates fully by documenting the id parameter's accepted forms (AIR-SEC-010, ri-10, 10, title) and the effect of include_sections. This gives an agent concrete grounding for both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('one AIGF risk by id'), and it clarifies the identifier formats accepted. This differentiates it from siblings like list_risks (which returns many) and get_control (which targets controls rather than risks).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'by id' wording makes clear this is for retrieving a single known risk, and the mention of title/ID formats helps an agent know when it has a valid lookup key. It does not explicitly name alternatives or list when-not-to-use conditions, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_controlsARead-onlyIdempotent
List AIGF controls (the framework calls them mitigations). Filter by type (PREV = preventative, DET = detective) or status. Returns ids for get_control.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| type | No | ||
| status | No | ||
| page_size | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| page | Yes | |
| items | Yes | |
| total | Yes | |
| page_size | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the call as read-only, idempotent, and non-destructive. The description adds useful behavioral context: it returns IDs intended as input for get_control and explains that 'mitigations' is AIGF's name for controls, which helps an agent interpret downstream data. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences provide the action, alternate vocabulary, filter semantics, and the return/next-step hint with no filler. All information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with an output schema and safe annotations, the description covers purpose, filters, and downstream usage. It does not enumerate possible status values, but the schema leaves status as an open string and the search_status sibling can handle discovery; this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry parameter meaning. It does for the two significant filters: it defines PREV and DET and says status is a filter. Page and page_size are left to their self-explanatory names/defaults, which is acceptable for a list endpoint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description begins with a specific action and resource ('List AIGF controls') and clarifies the framework's alternate terminology ('the framework calls them mitigations'), so there is no ambiguity about what is being listed. It also distinguishes itself from siblings like get_control (single item) and list_risks (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys when to use the tool: to list/filter controls by type or status, and to obtain IDs for a follow-up get_control call. It does not explicitly contrast with alternative list/search sibling tools, but the workflow hint is clear enough to route an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_reference_frameworksARead-onlyIdempotent
List the external reference frameworks the AIGF crosswalks to, with entry counts and how many risks and controls cite each.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| frameworks | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context by specifying the scope ('crosswalks to') and the aggregation details (entry counts, risk/control citations), which is useful beyond the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence states the verb, resource, and output details with no wasted words. Every part of the description contributes to an agent's understanding of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter list operation with rich annotations and an output schema, the description is complete: it says what is listed and what summary information is returned. Nothing essential is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter semantics to document. The baseline for zero-parameter tools is 4, and the description appropriately adds scope and output granularity without needing to explain any arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('external reference frameworks the AIGF crosswalks to'), and it specifies the output shape: entry counts plus risk/control citation counts. This clearly distinguishes it from siblings like search_framework, find_by_external_reference, and list_risks/list_controls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for enumerating reference frameworks and their citation counts, rather than searching or mapping. However, it does not explicitly state when to prefer this tool over siblings like search_framework or find_by_external_reference, leaving the routing decision mostly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_risksARead-onlyIdempotent
List AIGF risks. Filter by type (RC = regulatory and compliance, OP = operational, SEC = security) or document status. Returns ids you can pass to get_risk.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| type | No | ||
| status | No | ||
| page_size | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| page | Yes | |
| items | Yes | |
| total | Yes | |
| page_size | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by explaining the return shape ('Returns ids you can pass to get_risk') and the filter behavior, which goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the core purpose is front-loaded. Every sentence adds useful information, and the tool is immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering side-effect safety, the description provides the key missing context: how to filter and how to chain results into get_risk. Minor gaps remain around pagination and status values, but defaults and output schema cover part of that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the meaningful values for 'type' (RC, OP, SEC) and mentions 'document status', but it does not clarify page/page_size behavior or enumerate possible status values. Partial compensation, not full.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List'), a clear resource ('AIGF risks'), and the available filters. It also distinguishes itself from get_risk by explicitly noting that it returns ids to pass to get_risk, making the tool's role in a workflow clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context by explaining this tool is for listing/filtering risks and that its ids feed into get_risk. It does not explicitly exclude alternatives like list_controls, but the resource and filter details make the intended use reasonably unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
map_control_to_externalARead-onlyIdempotent
Crosswalk one control to external frameworks: NIST SP 800-53 r5, NIST AI 600-1, ISO 42001, EU AI Act, OWASP LLM/ML/ASI, FFIEC, IOSCO, SR 11-7 and others. Optionally restrict to the named frameworks (see list_reference_frameworks).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| frameworks | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| refs | Yes | |
| title | Yes | |
| control_id | Yes | |
| frameworks | Yes | |
| citation_uri | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that this is read-only, idempotent, and non-destructive, so the description does not need to restate safety. It adds useful scope context (supported frameworks and optional restriction), but it does not disclose behavior around unknown control IDs or empty mapping results; the output schema helps cover return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences front-load the verb and object, then give the framework list and the optional restriction in a single clause. There is no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema, annotations, and sibling context, the description is nearly complete for tool selection and invocation. It names the framework set, explains the optional filter, and points to the relevant sibling for framework discovery; the only notable gap is the under-specified id parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the frameworks parameter well by tying it to named frameworks and list_reference_frameworks, but the required id parameter is only implied as 'one control' with no stated source or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Crosswalk') and resource ('one control') and enumerates the target external frameworks, making the tool's scope immediately clear. It is easily distinguished from siblings like map_risks_to_controls and find_by_external_reference, which address different mapping directions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly communicates the intended use case—mapping a single control to external frameworks—and points to list_reference_frameworks for valid framework names. It does not explicitly state when to prefer alternative tools such as find_by_external_reference, so it lacks formal exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
map_risks_to_controlsARead-onlyIdempotent
Map risks to the controls that mitigate them. Pass explicit risk_ids (up to 25), a free-text query (the top k matching risks are used), and/or up to 5 queries (each contributing its own top k matches, unioned with everything else) -- useful for "both X and Y" questions where a single query blurs together two distinct concepts. Controls are ordered by how many of the given risks they cover; control_type (PREV or DET) restricts the result. Reports uncovered risks and any inputs that did not resolve.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | ||
| query | No | ||
| queries | No | ||
| risk_ids | No | ||
| control_type | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| edges | Yes | |
| risks | Yes | |
| controls | Yes | |
| unresolved | No | Inputs that did not resolve to a risk. |
| uncovered_risks | No | Risk ids with no mapped control. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnly/idempotent annotations by disclosing important behavior: controls are ordered by coverage count, control_type restricts results, uncovered risks are reported, and unresolved inputs are surfaced. This gives the agent accurate expectations for the tool's output and edge-case handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence carries operational value: input modes, limits, union semantics, ordering, filtering, and reporting behavior. It is front-loaded with the core purpose and avoids filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a 5-parameter tool with no required parameters and an output schema present, the description covers all relevant invocation semantics, constraints, and result-shaping behavior. An agent can correctly decide how to call this tool for single, multi-query, id-based, and filtered mapping scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully: it explains risk_ids (up to 25), free-text query behavior (top k matching risks), up to 5 queries with unioned results, control_type as PREV or DET, and k as the match count. Every parameter's role is described beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Map risks to the controls that mitigate them.' It clearly distinguishes the tool from sibling list/get/search tools by focusing on the mapping relationship and the combination of risks-to-controls coverage semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance on when to use each input mode and specifically calls out the multi-query use case for 'both X and Y' questions. It does not explicitly name alternative sibling tools or state when not to use this tool, but the usage context is strongly implied and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_frameworkARead-onlyIdempotent
Full-text search over risks and controls. Each hit has an id, the matching section, a snippet, and an aigf:// citation URI. Use scope to limit to risks or controls.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | ||
| query | Yes | ||
| scope | No | all |
Output Schema
| Name | Required | Description |
|---|---|---|
| hits | Yes | |
| query | Yes | |
| scope | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to restate those. It adds useful behavioral detail about result shape, including the aigf:// citation URI and snippet semantics, which goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences front-load the core purpose, then add output-shape details and a usage tip. Every sentence earns its place with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with a strong annotation profile and an output schema, the description covers the key behavioral aspects: target resources, hit structure, and scope filtering. Nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needed to explain parameters. It only clarifies 'scope' and implies that 'query' is free-text, while 'k' receives no explanation. With low schema coverage, this compensation is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Full-text search over risks and controls,' which gives a specific verb, resource, and scope. It also enumerates hit fields (id, matching section, snippet, aigf:// citation URI), making the tool's purpose concrete and distinguishable from sibling get/list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Full-text search' implies when to use it, and 'Use scope to limit to risks or controls' gives parameter-level guidance. However, it does not explicitly contrast this tool with sibling tools like list_risks, get_risk, search_status, or map_risks_to_controls, nor does it state when search is preferable to direct lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_statusARead-onlyIdempotent
Report search_framework's active retrieval mode: whether it is BM25-only
(lexical) or fused with dense semantic search (hybrid), and why -- e.g. the
semantic extra is not installed, or a model failed to load.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| mode | Yes | |
| model | No | |
| semantic_status | Yes | |
| semantic_enabled | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context by explaining that the tool reports not just the mode but the underlying reason, with concrete examples like missing 'semantic' extra or model load failure. This goes beyond the annotation metadata without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly written sentence that front-loads the core purpose and then provides useful explanatory detail and concrete examples. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only status tool with an output schema available, the description is comprehensive enough. It tells the agent what the tool reports, why it matters, and what kind of reasons might appear, leaving no critical gap for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the description does not need to explain parameter behavior. It still adds semantic value by describing what the status output is about, satisfying the baseline for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Report') and identifies the exact resource and concern: search_framework's active retrieval mode, including whether it is BM25-only or hybrid and why. This clearly distinguishes it from sibling tools like search_framework, which performs searches, and server_info, which reports general server state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for diagnosing search_framework's retrieval configuration, and the read-only annotations reinforce when it is safe to call. However, it does not explicitly name alternatives or conditions when another tool should be used instead, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
server_infoARead-onlyIdempotent
Describe this server: standard version, upstream provenance, exposed counts, latency, policy.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| tools | No | |
| counts | No | |
| policy | No | |
| latency | No | |
| version | Yes | |
| standard | Yes | |
| read_only | No | |
| resources | No | |
| upstream_ref | No | |
| upstream_repo | No | |
| upstream_commit | No | |
| standard_version | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds value by listing the exact informational dimensions returned (version, provenance, counts, latency, policy), but does not disclose any additional behavioral traits such as whether the information is cached, whether the call itself may be slow due to latency measurement, or how policy is represented. With annotations present, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core action and then provides a compact, informative list of the six content areas. There is no filler, repetition, or extraneous context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only informational tool with an output schema, the description covers the essential purpose and content scope. It could be slightly more explicit about what 'exposed counts' and 'policy' mean, but the presence of an output schema compensates for any ambiguity about return structure. Overall, it is adequate and complete for this low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so parameter semantics are trivially satisfied. Per the baseline for 0-parameter tools, the description need not compensate for missing parameter documentation. It also avoids inventing unnecessary parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Describe') and a clear resource ('this server'), then enumerates the dimensions it covers: standard version, upstream provenance, exposed counts, latency, and policy. This clearly distinguishes it from the sibling risk/control tools, which concern controls, risks, and frameworks rather than server metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Although there is no explicit 'when to use' statement, the context is clear: this is the only server-info tool among siblings that all address risk/control/framework operations. An agent can infer it should be used when server metadata is needed. It lacks an explicit exclusion or alternative, but the sibling set makes the use case unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
11 tool updates
v0.1.0- First observed
find_by_external_reference - First observed
get_control - First observed
get_risk - First observed
list_controls - First observed
list_reference_frameworks - First observed
list_risks - First observed
map_control_to_external - First observed
map_risks_to_controls - First observed
search_framework - First observed
search_status - First observed
server_info
TDQS
Scored across 11 tools
Most tools clearly target a distinct resource and action: list/get pairs for risks and controls are unambiguous, and the crosswalk tools are complementary. However, get_control and map_control_to_external both expose crosswalk references, and search_framework could be seen as overlapping with the list tools, though descriptions mostly clarify the difference.
The dominant naming pattern is verb_noun: list_risks, get_risk, list_controls, get_control, search_framework, list_reference_frameworks, find_by_external_reference, map_risks_to_controls. The only notable deviation is server_info, which is a noun rather than a verb-noun form, so the set is mostly consistent with minor exceptions.
With 11 tools, the server is well-scoped for a read-only AIGF framework explorer covering list, get, search, mapping, and crosswalk operations. Each tool serves a useful purpose, and the count feels appropriate without redundancy or bloat.
The toolset covers the apparent domain comprehensively: retrieving risks and controls, mapping between them, searching, forward and reverse crosswalk to external frameworks, listing supported frameworks, and server diagnostics. For a read-only reference and mapping server, there are no obvious dead ends or missing operations.
Maintenance
Related MCP Connectors
Connect AI agents to financial institution origination, analytics, and compliance workflows.
Agent-native security, trust, reliability, data and procurement tools for AI workflows.
Sanctions screening, KYB, identifier validation, jurisdiction risk & secret scanning for AI agents
Read-only finance and operations controls for AI agents with evidence and safe next actions.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to understand and query your database safely by providing a semantic layer of metadata, with tools to search, explain, validate, and generate safe SQL.2MIT

ibm-watsonx-gov-catalog-mcpofficial
AlicenseNot gradedqualityDmaintenanceBridges AI agents with tools on IBM watsonx governed agentic catalog, enabling secure governance and tool invocation via the Model Context Protocol.1Apache 2.0- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with the OSDU® data platform through Model Context Protocol, providing tools for search, storage, schema management, and dataset operations.1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceExposes Iceberg-backed ontology objects, links, and actions as typed MCP tools for LLM agents, enabling governed data access and operations without raw SQL.MIT