aeat.entrypoints.mcp._terminology_tools module¶

The aeat_terminology_search tool: look up taxpayer-facing tax vocabulary.

ADR R3’s grounding surface has a second half: the bundled Terminology Handbook, the ratified taxpayer/operator vocabulary. This tool lets the model resolve a plain-language term (“prorrata”, “recargo de equivalencia”) to its preferred label, short description, and concept id, so the assistant explains a concept in the taxpayer’s own words rather than inventing a definition. Only approved-lifecycle concepts are searched (the taxpayer-facing set), per the glossary-concepts-are-taxpayer-facing rule the application service already enforces.

Like _corpus_tools / _harness_tools, this module is SDK-independent pure functions over typed models; build_terminology_search_tool() lazily adapts onto the MCP SDK’s Tool type so the module imports (and the server refuses gracefully) without the aeat-cli[agent] extra. The search itself is owned by the application service (search_terminology()), consumed through the package facade per service-imports-via-top-level-reexports.

TERMINOLOGY_SEARCH_TOOL¶: The terminology tool’s MCP name (the terminology.search verb).

class TerminologyResultRow(**data)[source]¶

Bases: BaseModel

One terminology hit surfaced to the model.

Parameters:

concept_id (str)
preferred_label (str)
short_description (str)
matched_on (str)

concept_id: str¶

preferred_label: str¶

short_description: str¶

matched_on: str¶

class TerminologySearchPayload(**data)[source]¶

Bases: BaseModel

The terminology tool’s structured result.

Parameters:

query (str)
results (tuple[TerminologyResultRow, ...])

query: str¶

results: tuple[TerminologyResultRow, ...]¶

terminology_payload_from_hits(query, hits)[source]¶

Map ranked terminology hits to the tool’s typed payload.

Return type:

TerminologySearchPayload

Returns:

A TerminologySearchPayload.

Parameters:

query (str)
hits (tuple[TerminologyHit, ...])

build_terminology_search_payload(query, *, locale='es', limit=8)[source]¶

Run terminology search for query and return the tool payload.

Return type:

TerminologySearchPayload

Returns:

A TerminologySearchPayload.

Parameters:

query (str)
locale (str)
limit (int)

render_terminology_search_text(payload)[source]¶

Render the payload as markdown for the tool’s text content.

Return type:: str
Parameters:: payload (TerminologySearchPayload)

build_terminology_search_tool()[source]¶

Build the SDK Tool for the terminology search tool.

Lazily imports the SDK types so the module imports without the aeat-cli[agent] extra. Annotated readOnlyHint / idempotentHint.

Return type:: Tool
Returns:: The aeat_terminology_search Tool object.