Skip to main content
Glama

finos-mcp

ci controls schemas tools tests recall@5 hallucinated ids

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

finos-mcp-aigf

AI Governance Framework

Risks and controls with their public AIR-* ids, risk-to-control mapping, crosswalks to NIST / ISO 42001 / EU AI Act / OWASP, full-text search, citable resources

finos-mcp-cdm

Common Domain Model

Type descriptions, product and payout catalogue, event qualification, and validation of CDM JSON objects (Rune and legacy formats)

finos-mcp-fdc3

FDC3

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 serve tools/* if any tool lacks it.

  • Rate limits. Token bucket per client and tool; exhaustion is a JSON-RPC error (-32029, rate_limited) with retry_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_large result; oversized results are replaced with output_too_large and 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 unless FINOS_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 8000

Or 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 8000

See 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/*/src

Licenses

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 tools
find_by_external_referenceA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
keyYes
frameworkNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
keyYes
matchesYes
frameworkNo

TDQS

A4.6/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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_controlA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
include_sectionsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
typeYes
titleYes
statusYes
summaryYes
sectionsNo
sequenceYes
short_idYes
mitigatesNo
referencesNo
type_labelYes
source_pathYes
citation_uriYes
related_controlsNo

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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_riskA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
include_sectionsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
typeYes
titleYes
statusYes
summaryYes
sectionsNo
sequenceYes
short_idYes
referencesNo
type_labelYes
source_pathYes
citation_uriYes
mitigated_byNo
related_risksNo

TDQS

A4.6/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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_controlsA
Read-onlyIdempotent

List AIGF controls (the framework calls them mitigations). Filter by type (PREV = preventative, DET = detective) or status. Returns ids for get_control.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
typeNo
statusNo
page_sizeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
pageYes
itemsYes
totalYes
page_sizeYes

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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_frameworksA
Read-onlyIdempotent

List the external reference frameworks the AIGF crosswalks to, with entry counts and how many risks and controls cite each.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
frameworksYes

TDQS

A4.3/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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_risksA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
typeNo
statusNo
page_sizeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
pageYes
itemsYes
totalYes
page_sizeYes

TDQS

A4.2/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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_externalA
Read-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).

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
frameworksNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
refsYes
titleYes
control_idYes
frameworksYes
citation_uriYes

TDQS

A4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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_controlsA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
kNo
queryNo
queriesNo
risk_idsNo
control_typeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
edgesYes
risksYes
controlsYes
unresolvedNoInputs that did not resolve to a risk.
uncovered_risksNoRisk ids with no mapped control.

TDQS

A4.8/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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_frameworkA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
kNo
queryYes
scopeNoall

Output Schema

ParametersJSON Schema
NameRequiredDescription
hitsYes
queryYes
scopeYes

TDQS

A4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters2/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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_statusA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
modeYes
modelNo
semantic_statusYes
semantic_enabledYes

TDQS

A4.5/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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_infoA
Read-onlyIdempotent

Describe this server: standard version, upstream provenance, exposed counts, latency, policy.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
nameYes
toolsNo
countsNo
policyNo
latencyNo
versionYes
standardYes
read_onlyNo
resourcesNo
upstream_refNo
upstream_repoNo
upstream_commitNo
standard_versionNo

TDQS

A4.2/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

  1. 11 tool updatesv0.1.0
    • First observedfind_by_external_reference
    • First observedget_control
    • First observedget_risk
    • First observedlist_controls
    • First observedlist_reference_frameworks
    • First observedlist_risks
    • First observedmap_control_to_external
    • First observedmap_risks_to_controls
    • First observedsearch_framework
    • First observedsearch_status
    • First observedserver_info

TDQS

A4.3/5.0

Scored across 11 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness5/5

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

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    C
    maintenance
    Enables 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.
    2
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to interact with the OSDU® data platform through Model Context Protocol, providing tools for search, storage, schema management, and dataset operations.
    1
    Apache 2.0