Skip to main content
Glama

map_to_taxonomy

Read-onlyIdempotent

Maps everyday business terms like customer service or GenAI copilot to canonical AI BVF taxonomy values for scoring, returning matches or suggestions when wording is ambiguous.

Instructions

Map everyday business language to the canonical AI BVF values required by the scoring tools. CALL THIS when the user says customer service, procurement, banking, GenAI copilot or bureaucratic and the matching enum is not certain. Pass only the fields written in free text; each returns the canonical value, what it matched on, or null with suggestions. Words match whole, never inside another word, and the longest phrase wins. A null result requires the user to choose from the suggestions, because a plausible guess would change the score. When candidates are returned the wording pointed to more than one value: ask the user to pick between them. Use list_taxonomy when the user needs every permitted value, then pass the mapped values into score_initiative, diagnose_process, get_benchmark or the portfolio tools. Deterministic lookup with no authentication. Anonymous usage telemetry may be sent; set AIBVF_TELEMETRY_DISABLE=1 to opt out.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "map_to_taxonomy"
  }
}

Input Schema

NameRequiredDescriptionDefault
ai_tierNoEveryday AI language, e.g. RPA, GenAI copilot, autonomous agents. Resolved to gen1/gen2/gen3.
functionNoEveryday function language, e.g. customer service, procurement, legal, people. Resolved to cx, supply, risk, hr and so on.
industryNoEveryday industry language, e.g. banking, ecommerce, pharma. Resolved to the canonical enum.
readinessNoEveryday culture language, e.g. bureaucratic, cross-functional, hierarchical. Resolved to agile/traditional/siloed.

Output Schema

NameRequiredDescriptionDefault
ai_tierNo
functionNo
guidanceYes
industryNoinput, resolved and matched_on; or resolved null with suggestions when no confident match, plus candidates when the wording pointed to more than one value.
readinessNo
bvf_versionYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.15.2
    • changedOutput schema / properties / industry / description
      Previous value: -"input, resolved and matched_on; or resolved null with suggestions when no confident match."New value: +"input, resolved and matched_on; or resolved null with suggestions when no confident match, plus candidates when the wording pointed to more than one value."
  2. Addedv0.14.14

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, closed-world and non-destructive, but the description goes further: deterministic lookup, no authentication, anonymous telemetry with an AIBVF_TELEMETRY_DISABLE=1 opt-out, and the matching rules (whole-word only, longest phrase wins). It also discloses failure semantics — null plus suggestions, or multiple candidates meaning ambiguous input — and warns that guessing would change the score.

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-loads purpose and the CALL THIS trigger, then matching rules, then null/candidate handling, then alternatives and downstream tools. Dense and mostly earning its place, though the telemetry opt-out sentence is somewhat tangential to selection and invocation.

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 4-param, all-optional, deterministic lookup, the description covers triggering conditions, matching semantics, null and multi-candidate handling, alternatives and downstream consumers. An output schema exists, so the brief mention of return values is a bonus rather than a 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 100%, so the baseline is 3, but the description adds real meaning by saying to 'pass only the fields written in free text', implying partial population is valid and that canonical enum values should not be supplied. It also clarifies the per-field return shape, though it does not illustrate accepted free-text phrasing beyond the examples already in the 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?

States a specific verb and resource ('map everyday business language to the canonical AI BVF values') plus the downstream reason ('required by the scoring tools'). This clearly separates it from list_taxonomy, which enumerates values rather than resolving free text.

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?

Gives an explicit trigger ('CALL THIS when the user says customer service, procurement, banking, GenAI copilot or bureaucratic and the matching enum is not certain') and names the alternative with its selecting condition ('Use list_taxonomy when the user needs every permitted value'). It also routes results onward to score_initiative, diagnose_process, get_benchmark and the portfolio tools.

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