Deterministic identity for structured descriptors using the MAP v1 canonical format
MAP v1.1 is a cryptographic specification library, not an agent-oriented MCP tool server. The 19 tools exposed are direct API wrappers around low-level hashing, canonical serialization, and projection functions. While the underlying library is well-engineered (multi-language implementations, conformance test suite, clear spec), the tool definitions exhibit systematic gaps that make them unsuitable for autonomous agent planning: (1) Tool names lack action verbs, 'midFull' reads as a function name, not an imperative action; 'CanonBytesFull' is similarly passive. LLMs depend on verb-based names to infer intent. (2) Descriptions are terse (10 - 40 chars) and assume domain expertise in MAP v1 specification semantics (§2.2, §3.7, §6.2 references); they do not explain WHEN an agent should choose this tool over alternatives, or WHAT business problem it solves. (3) Parameter schemas are minimal, types are declared but descriptions are brief and sometimes cryptic ('Any canonical-model value', 'Value'). (4) Return types are undocumented, no schema for MID string format, buffer structure, or error payloads. (5) Error handling is implicit (MapError with codes) but tool descriptions do not guide recovery. (6) The tool set reflects a library API, not an agent-composable interface, tools operate at the cryptographic layer (hashing, serialization) rather than domain tasks (validate identity, prove descriptor ownership, verify chain).
Select fields from descriptor by JSON Pointer paths (§2.3).
Return CANON_BYTES for BIND projection.
Return CANON_BYTES for FULL projection.
Return the highest-precedence code from a set of detected violations (§6.2).
Return descriptor unchanged (§2.2).
Compute MID over selected fields (§7.2).
Compute MID from raw UTF-8 JSON bytes (JSON-STRICT + BIND).
Validate pre-built CANON_BYTES and return MID (fast-path §3.7).
Tool names lack action verbs. Names like 'midFull', 'CanonBytesFull', 'FullProject' read as function/class names, not agent directives. LLMs rely on imperative verbs (compute_, get_, validate_) to infer tool intent and decide when to invoke. Passive or function-style names force the agent to read full descriptions before deciding, wasting reasoning cycles and increasing misselection risk.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 32 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 48 | - | v1 |
Compute MID over the full descriptor (§7.2).
Compute MID from raw UTF-8 JSON bytes (JSON-STRICT + FULL).
Return CANON_BYTES for selected fields (BIND projection).
Return CANON_BYTES (header + MCF) for the full descriptor.
Given multiple error codes, return the highest-precedence one (§6.2).
Compute a MID over selected fields (BIND projection).
Compute a MID from raw UTF-8 JSON bytes (JSON-STRICT + BIND).
Validate pre-built CANON_BYTES and return MID (fast-path §3.7).
Compute a MID over the full descriptor (FULL projection).
Compute a MID from raw UTF-8 JSON bytes (JSON-STRICT + FULL).
Normalize a JS object for MID computation (convenience).
Descriptions are terse (10 - 40 chars) and assume deep domain knowledge of MAP v1 specification (§2.2, §3.7, §6.2 references). They do not answer: WHEN should an agent choose this tool? WHAT business problem does it solve? WHAT does the output look like? Example: 'Compute a MID over the full descriptor (FULL projection).' assumes the agent knows what FULL projection means and why it matters. A production tool should say: 'Hash a complete descriptor using the MAP v1 canonical format to generate a deterministic identifier (MID). Use when you need a unique, stable hash for verification or governance.' Spec references (§3.7) are useless to LLM reasoning, describe the behavior in plain language.
Input parameter descriptions are minimal or absent. 'descriptor' is documented as 'Any canonical-model value' (what is canonical-model? What types are allowed?). 'pointers' is described as 'RFC 6901 JSON Pointer strings' (hyperlink reference, not explanation, agent doesn't know if ['/foo', '/bar'] or ['/foo/0'] is correct). Missing descriptions: What should the agent pass? What formats are valid? What happens on invalid input? Example fix: 'pointers: Array of RFC 6901 JSON Pointer paths (e.g., ["/name", "/metadata/owner"]) selecting which fields of the descriptor to hash. Required. At least one pointer must be provided; duplicates are ignored.'
Return type schemas are undocumented. Tools return strings (MID), Buffers (CANON_BYTES), or objects (prepare result), but the tool definitions do not specify: What is the structure of the MID string? Is it always 'map1:' + hex? What is the structure of returned objects from prepare()? Does chooseReportedError return a single error code string or a structured error object? Without documented output schemas, agents cannot plan downstream tool calls or extract required fields reliably.
Error handling and recovery guidance is absent from tool descriptions. Tools raise MapError with codes (ERR_CANON_HDR, ERR_DUP_KEY, etc.) but descriptions do not explain: When would this error occur? What should the agent do to recover? Is it retryable? Should the agent ask the user for input? Example: 'If you see ERR_DUP_KEY, the descriptor has duplicate object keys, normalize the input before retrying. If you see ERR_LIMIT_DEPTH, the descriptor is nested too deeply, flatten it or split into sub-descriptors.' Current descriptions offer no guidance.
Tool set mirrors a cryptographic library API, not an agent-composable domain interface. Tools expose low-level functions (hash descriptor, serialize to bytes, project fields) rather than high-level business operations (validate identity, prove descriptor ownership, compare identities, resolve descriptor conflicts). An agent cannot accomplish a meaningful task by composing these tools, they lack a business context. Consider exposing higher-level tools: validate_descriptor_identity(descriptor, claimed_mid) → boolean; compare_descriptors(old, new) → changed_fields; resolve_descriptor_version(descriptor_id) → latest_descriptor. This would make the tool set useful to agents solving real problems.
No parameter validation constraints or format specifications. 'descriptor' accepts 'any canonical-model value' but what types are rejected? What are the limits on object depth, array length, string length, number magnitude? 'pointers' are RFC 6901 JSON Pointers but no validation rule is stated. Tools likely enforce these server-side but agents cannot self-correct invalid input, they will retry blindly or hit timeouts. Add explicit constraints to parameter descriptions: 'descriptor: Max depth 50, max string length 1MB, max array length 10000. No circular references.'; 'pointers: Each pointer max 256 chars, array max 100 pointers, no duplicate pointers.'