pain001-mcp

List faces

list_faces

Read-onlyIdempotent

Lists the pain.001 projection targets and their accepted bindings so you can choose a face and supply required bank-specific values before projecting a payment message.

Instructions

List the faces: the standards a pain.001 document can be projected into.

Use this before ``project_face`` to pick a target and to learn which
bindings it accepts. A binding is a value the payment message does
not carry, such as the UK Open Banking ``ConsentId`` agreed with the
bank; any key a face does not list is refused.

Delegates to :func:`pain001.faces.list_supported_faces`.

Returns:
    ``{"count", "faces": [{"name", "description", "bindings"}, ...]}``,
    or ``{"error": ...}`` when the installed pain001 has no faces.

Input Schema

Name	Required	Description	Default
No arguments

Output Schema

Name	Required	Description	Default
`count`	No
`error`	No
`faces`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.0.78Nov 7, 2026

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 genuinely new context: the meaning of 'bindings' (values the payment message does not carry, e.g. UK Open Banking ConsentId) and that unlisted binding keys are refused. It also discloses the error path when the installed pain001 has no faces, which annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the pre-requisite workflow, then the binding concept, then the return shape. The UK Open Banking ConsentId example earns its place by making an abstract term concrete. The 'Delegates to pain001.faces.list_supported_faces' line is an implementation detail of little value to an agent and is the one stray sentence.

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?

The tool is simple, has no inputs, and has an output schema; the description still spells out the return shape and the degenerate error case, plus the refusal rule for unknown bindings. Nothing an agent needs to call this and hand off to project_face is missing.

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 takes zero parameters, so the baseline is 4. The description correctly spends no words on inputs and instead explains the conceptual domain of the returned 'bindings' field, which is the only semantic ambiguity an agent would face.

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?

States a specific verb and resource ('List the faces') and immediately defines the domain term as 'the standards a pain.001 document can be projected into'. This makes it unambiguously distinct from sibling tools like list_supported_formats and from project_face, which acts on a chosen face.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly prescribes the workflow: 'Use this before project_face to pick a target and to learn which bindings it accepts.' That names the alternative, the ordering constraint, and the downstream consumer of the result, leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.