emem, the verifiable memory protocol for the physical world

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

The description goes well beyond the annotations by disclosing the locate → recall → algorithm chain, auto-materialization of satellite/elevation/water bands on miss, the envelope's contents, signed receipts at response root, caveats block, out-of-scope null routing, and include_image latency. This richly supplements the readOnlyHint/idempotentHint/destructiveHint 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.

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

The description is front-loaded with the core purpose and includes a useful example, but it is lengthy and repeats certain ideas such as signed receipts and envelope structure. While well-organized into paragraphs, it could be trimmed without losing essential guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with no output schema and 10 parameters, the description is exceptionally complete: it states what the server does, what the response envelope contains, what is signed, how to handle out-of-scope questions, effect of include_image, verbose default, and the trade-offs. An agent has sufficient context to decide when to call it and what to expect in return.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds meaningful guidance: forward the user's question verbatim as q, extract the noun phrase for place, choose among place/cell/lat+lng, and understand verbose/include_image trade-offs like the 25 KB MCP cap and 1-2 s latency. This goes beyond the schema's already detailed property descriptions, though some duplication exists.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-plus-resource: 'Single-shot free-text answer about a real-world location, backed by signed satellite/elevation/water/built-up receipts.' It clearly distinguishes emem_ask from sibling tools like emem_locate or emem_recall by framing this as a packaged, question-answering endpoint that composes primitives server-side.

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

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

The description includes an explicit 'When to use' section stating to use this tool when the question concerns a specific real-world place and a packaged, citation-bearing answer is preferable to manual primitive composition. It also gives input-selection guidance (q plus place/cell/lat-lng) and explains out-of-scope behavior, though it does not explicitly name sibling tools to avoid.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses critical runtime behavior: it returns matches and drift on mismatch, bare cids produce `degraded: true` and skip cell-binding, damaged cids are refused, and strict mode alters only the respelled-number case. It also warns that JSON numbers lose trailing digits during stringification—a vital nuance not inferable from annotations.

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

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

The description is front-loaded with the core purpose, then moves to usage context, edge cases, and an example. Every sentence adds operational value—there is no fluff, no repetition of annotations, and the structure makes it easy to scan for key instructions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 parameters, an output schema, and strong annotations, this description is thoroughly complete. It covers return values (matches/drift), citation validation nuances, strict-mode semantics, and concrete use cases. The link to the underlying verify operation and the example arguments round it out, leaving no critical operational gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema coverage, the description significantly deepens each parameter's meaning. For `claimed_value` it explains why to send a string ('character for character as you will emit it') and what happens if a number is sent; for `token` it explains bare cid and damaged cid behaviors; for `strict` it precisely scopes the sole outcome change. This far exceeds the schema's basic descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise operational statement: 'Grade a value you are about to emit against the signed fact your citation points at.' It specifies the verb (grade), the resource (signed fact), and the context (pre-publish validation), and it clearly distinguishes itself from sibling tools like emem_verify_receipt by being the pre-emission check rather than a receipt lookup.

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

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

The 'When to use' section explicitly directs: 'Call immediately before publishing, logging, or handing on any value you took from an emem fact' and instructs to treat a false matches as a gate. It also names the complementary tool `value_verbatim` from resolve, providing an alternative and pairing strategy. This is explicit and actionable guidance.

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

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

Annotations (idempotentHint=true, readOnlyHint=false) are complemented by description details: the same entity_cid is minted for the same object, external IDs dominate identity resolution, and a signed receipt is returned. This adds meaningful behavioral context beyond the annotations without any contradiction.

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

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

The description is lengthy but well-structured: purpose first, then usage guidance, exclusions, and an example. Every paragraph earns its place given the tool's complexity and many siblings; it is verbose but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers return values, how to reference the entity later, sibling distinctions, and anchoring constraints, all for a complex tool with 8 parameters and no output schema. It is exceptionally complete for an agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are already well-defined. The description adds value by explaining the relationship between anchoring parameters (place/cell/lat+lng) and noting that caller-supplied external_ids win over geocoder-derived ones, plus a concrete example. This enriches beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb+resource ('Give a real-world object a single, shared, content-addressed identity') and clearly states the return value (entity_token plus signed receipt). It explicitly differentiates from siblings like emem_entity_resolve and emem_entity_link, making the tool's unique scope unambiguous.

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

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

The 'When to use' paragraph gives explicit context (conversations referencing a THING) and directly names alternatives (emem_entity_resolve for already-registered identities, emem_entity_link for linking existing spellings), plus clear 'Do NOT call' exclusions for observations and places. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, establishing the operation as a non-destructive mutation. The description adds meaningful context beyond the annotations, explaining that it 'Builds the shared reference graph' and ensures future `emem_entity_resolve` calls converge. No contradiction with annotations; the added context about graph construction and long-term effect is valuable.

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

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

The description is well-structured with a clear headline, a 'When to use' paragraph, and a concrete example. It is front-loaded with the core purpose, and every sentence serves a distinct role: definition, usage context, and illustration. No filler or redundancy; appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a nested object and no output schema, the description covers the purpose, usage scenarios, example arguments, and how it relates to the resolve tool. It does not describe return values, but since this is a mutation tool without an output schema, that is not a significant gap. It could be more explicit about idempotency or signing, but annotations fill some gaps, making it adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by naming the specific external id types (GERS / OSM / Wikidata) that map to the nested `external_ids` parameter, and the example arguments demonstrate the intended structure for `entity_token` and `alias`. The description clarifies that `alias` is an alternate label, which reinforces but also goes slightly beyond the schema's brief descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb-resource pair: 'Record a signed equivalence: bind an alternate label or a stable external id ... to an existing canonical object.' It explicitly mentions the consumer tool `emem_entity_resolve`, distinguishing this from sibling tools by explaining how it feeds the resolve process. The title and description align well.

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

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

The description provides a dedicated 'When to use' section with concrete scenarios ('when you learn that two phrasings denote the same object' or 'to attach an authoritative external id'). It clearly sets the context but does not explicitly state when NOT to use it or name alternative tools for exclusion. This matches the 'clear context, no exclusions' level.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral specifics: returns 'ranked existing candidates' for text input, 'narrow to a place' with near, and 'dereference it directly to the signed entity body' for a token. This goes beyond the structured safety hints by explaining the two execution paths and their outputs.

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

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

The description is organized into three paragraphs: purpose/modes, when-to-use, and an example. Each section has a distinct function and avoids redundant detail. The only slight redundancy is 'Read-only,' which duplicates the readOnlyHint annotation, but it does not bloat the description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking an output schema, the description clearly states what callers can expect: ranked candidate objects for text searches and the signed entity body for token dereference. The usage guidance and examples cover the main invocation patterns. The tool's complexity (two modes, 5 optional parameters) is adequately addressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% coverage of all five parameters, so the baseline is 3. The description adds meaningful usage semantics by explaining how text, near, and token interact: text triggers fuzzy search, near narrows by location, and token bypasses the search for direct dereference. It also gives a concrete example. However, it does not explain the k (max candidates) parameter, which remains schema-only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Converge'/'Resolve') and resource ('canonical object'), and explains the two modes: fuzzy text resolution and direct token dereference. This distinguishes it from siblings like emem_entity (minting) and emem_memory_token_resolve (general memory tokens).

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

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

The 'When to use' section explicitly instructs to call before minting when another agent may have registered the object, or when receiving an emem:entity: token. It also states 'resolve first, mint only if nothing matches,' providing a clear when-not and alternative.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description adds substantial behavioral detail: it returns a signed receipt over vectors read, explains scoring mode performance tradeoffs, and clarifies that an empty result means no nearby attested vector rather than absence of resemblance. It also states the tool 'materialises nothing', reinforcing the read-only nature. These disclosures provide valuable operational context not inferable from 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.

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

Despite its length, every sentence provides distinct value: core function, return shape, mode logic, k range, empty-result semantics, use-case triggers, key/band details, and an example. The 'When to use' section is clearly demarcated and front-loaded enough that the agent immediately grasps the tool's purpose. There is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the primary use case thoroughly: what it does, how to invoke it, what results look like, and how to interpret empty outputs. It also includes a concrete example. However, given the tool's complexity (10 parameters, nested objects, optional advanced filtering/time-travel), the description does not mention the existence of `scope`, `filter`, `as_of_tslot`, or `as_of_signed_at`, leaving the agent to discover those capabilities only through the schema. Also, with no output schema, the description's return-field summary is helpful but not exhaustive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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 enriches key parameters: it explains the `key` formats (cell64 or inline), the `band` options including the default and the multi_year variant, and the performance semantics of `mode` (cosine vs hamming vs hamming_then_rerank). It also gives the `k` range/default. This goes beyond the schema's terse descriptions, though it does not cover every parameter (scope, filter, as_of are left to schema).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'k-NN over the corpus by cell embedding or inline vector', which is a specific verb+resource statement that clearly identifies the tool's function. It further distinguishes from siblings by stating it returns 'neighbours' ordered by similarity and explicitly frames 'find places like X' as the use case. The title 'k-NN over the corpus by embedding' reinforces this without ambiguity.

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

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

The description includes a dedicated 'When to use' section with concrete user intents ('find places like X', 'where else looks like this', 'hands an embedding'). It gives clear context but does not explicitly name alternative tools or state when NOT to use this tool, so it falls short of full exclusions/alternatives guidance.

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

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

The description discloses several non-obvious behaviors beyond the annotations: it is advisory ("nothing is blocked"), never denies on unrecognized citations (open-world stance), returns allow if no content is read, and explains shape fallback behavior. These details meaningfully augment the readOnly/idempotent hints and help set correct expectations.

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

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

The description is longer than typical but well-structured: opening purpose, denial-code reference, advisory note, memory-algebra link, when-to-use, enforcement alternative, and example. Each section earns its place, though the URL and some repetition around claim_gating/shape could be trimmed. It is not bloated or rambling, but it also isn't as tight as a two-sentence description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple denial codes, fix actions, shape-based reading, advisory semantics) and the presence of an output schema, the description covers all necessary context: what the tool does, when to use it, what its limitations are, and how to invoke it with different frameworks. Nothing critical seems missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% parameter coverage with thorough descriptions for each parameter (shape, texts, messages, claim_gating). The tool description adds a concrete example argument and some context about shape behavior, but it largely restates what the schema already provides (e.g., claim_gating details, fallback to native). Since the schema does the heavy lifting, a score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: "Run emem-guard's policy pipeline over text you are about to send, against this responder's corpus." It clearly explains what is checked (emem:citations), what is returned (allow/deny with a machine-readable reason), and even lists the denial codes and fix actions. This distinguishes it from sibling tools like emem_verify_receipt and emem_echo_verify by focusing on pre-send draft verification against the responder's corpus.

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

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

There is an explicit "When to use" section stating to call it on your own draft or tool result before asserting/reasoning. It also names an alternative for enforcement (emem_guard_selfhost) and cautions about shape handling for non-native payloads. This is exactly the kind of guidance needed to choose this tool over siblings.

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

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

Beyond the annotations (readOnlyHint:false, idempotentHint:true, openWorldHint:true), the description discloses that the plan is EXECUTED in the same call, that unknown/missing type yields a needs_intent_type envelope rather than a hard error, and that every named tool dispatches by name at /mcp and /mcp/full even if not shown in tools/list. 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.

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

Although long, every sentence earns its place: the table condenses seven intents, the 'When to use' paragraph removes ambiguity, and the example anchors the schema. The structure (table, when-to-use, example) makes it scannable despite the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by stating the return envelope ('the resolved cell64, the similarity, the delta, the verdict') and the error shape (needs_intent_type). It also covers edge cases (unknown type, hidden tools, tslot source), making it fully self-sufficient for a complex 14-parameter tagged union.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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 a compact table mapping each intent to required/optional fields and answer shape, clarifies that fields for other intents are ignored (tagged union), and gives a concrete example. It also explains tslot semantics (band-tempo-relative, from emem_trajectory) beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a crystal-clear statement: 'Say what you want in one typed object and get the answer, without choosing a primitive.' It then distinguishes the tagged-union dispatcher from sibling primitives by naming exact alternatives (emem_recall, emem_recall_polygon, emem_ask) and gives the scope of each intent row in the table.

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

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

There is an explicit 'When to use' section: 'Call when the user's question maps cleanly onto one of the seven rows above and you would rather state the goal than pick a primitive. Reach past it for anything else.' It names the alternatives, explains the unknown-type behavior (structured needs_intent_type envelope), and gives concrete guidance about tslots and hidden tools.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description discloses additional behaviors: coordinates win over place text when both arrive, aliases q/query/name are accepted, and unknown arguments are reported in `_unrecognised_arguments` rather than erroring. It also outlines the response's three sub-fields, which is valuable given no output schema.

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

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

The description is somewhat long but well-structured: core purpose front-loaded, then alternatives, then parameter semantics, then when-to-use and response shape, ending with an example. No redundant sentences, though it could be tightened slightly without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden of explaining return values, and it does so in detail: live_bands_by_topic, algorithms_for_topic, and declared_but_no_materializer_at_this_responder. It also covers alias handling, coordinate precedence, and error-avoidance behavior, making it complete for a tool with 6 parameters and two input modes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with per-parameter descriptions, but the tool description adds richer semantics: it clarifies that lat/lng are paired and required together, that place/q/query/name are interchangeable aliases, and that coordinates take precedence when both are supplied. This goes beyond the schema's isolated field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb+resource: 'Mint the canonical, vendor-neutral address (cell64) for a real-world place' and also 'returns the topic-grouped inventory of bands and algorithms recallable there.' It explicitly differentiates from siblings by directing object-identity lookups to emem_entity and single-shot chain calls to emem_ask.

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

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

Explicit 'When to use' section says 'Use whenever the input refers to a real-world location and the next step needs the cell64 identifier or wants to know which bands are available before recalling.' It also names concrete exclusions: use emem_entity for object identity, and emem_ask for the packaged chain.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false, but the description goes far beyond them. It discloses that the responder signs over the full receipt, the bundle_token format, offline verifiability via /v1/verify_receipt, partial-resolution visibility via members/resolved, and CID preimage behavior with purpose. This is rich behavioral context crucial for an agent invoking the tool.

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

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

The description is structured with a clear opening, a 'When to use' section, and an example. It is longer than average, but the complexity of the tool merits detail. The 'Memory algebra: merge operation' link is somewhat cryptic and not integrated, slightly reducing conciseness, but overall every major sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains expected response fields (members and resolved) and verification via verify_receipt. It covers scope application, partial resolution, limits, and alternative tools. For a complex nested-object tool with no output schema, this description is unusually complete and actionable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with each parameter (scope, purpose, triples) already well described including the 256 cap and typed-400 failure. The description adds a practical example arguments block but does not materially introduce new parameter semantics beyond the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Compose N (cell, band, tslot?) triples into ONE signed envelope.' It clearly distinguishes from siblings by explicitly stating to use this 'instead of N separate emem_memory_token composers' when the citation is conceptually one thing. The title and body both reinforce a distinct, well-scoped purpose.

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

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

A dedicated 'When to use' section explicitly states: 'Call when the agent wants to cite multiple (place, band, vintage) facts as one handle.' It also names the alternative (N separate emem_memory_token composers) and provides a concrete example ('EUDR-relevant baseline for these 8 plots'). It adds practical constraints like the 256-triple cap and round-trip planning advice.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description discloses critical behavioral nuances: the default scope excludes same-attester sources, the zero result means something specific, severity is computed differently per band kind, and single-responder deployments need a different flag. This adds substantial context not present in annotations, and there is no contradiction.

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

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

The description is long but well-structured: purpose first, then usage, then an example. Every sentence adds meaningful information or useful nuance, and it never repeats empty phrases. The text is front-loaded with the core behavior and includes a punchy summary ('The opposite of a confident single answer') that efficiently communicates intent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately describes return values (severity, citations, `disagreement_scope`, providers) and covers edge cases (single-responder deployments, same-attester sources). It also references follow-up tools, making the description complete for a tool with this complexity and parameter count.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers 100% of parameters with rich descriptions, so the baseline is 3. The description adds extra value by giving example arguments (`{"cell_prefix":"damO",...}`), explaining how `cell_prefix` and `band` narrow the scan, and providing a conditional usage note for `include_same_attester_sources`. While some param details overlap with schema, the example and contextual guidance push it above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a crystal-clear verb+resource: 'Surface where the corpus DISAGREES with itself', then elaborates with return details (0-1 severity score, citations) and contrasts with the opposite behavior ('instead of silently picking one value'). This fully differentiates it from sibling tools like emem_recall or emem_ask, which answer with a single confident value.

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

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

An explicit 'When to use' section lists concrete triggers ('trust matters', 'is there disagreement', 'audit this claim') and even states the alternative follow-ups ('emem_diff', 'emem_edges_recall'). It also warns against misinterpreting a zero result and instructs when to set `include_same_attester_sources: true`, leaving no doubt about proper invocation context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond that, including the token format `emem:fact:<cell64>:<fact_cid>`, validation rules (non-empty, no `:` separator), the resolution guarantees, and the measured cost/context tradeoff. This significantly exceeds the annotation baseline and contains no contradictions.

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

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

The description is front-loaded with a clear purpose statement and then structured into 'When to use', cost analysis, and example sections. It is longer than many tool descriptions, but every part serves a decision-making or usage purpose. The cost analysis is quite detailed and could be trimmed slightly, but it is directly relevant to choosing between this tool and emem_memory_bundle, so it earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is exceptionally complete: it explains the purpose, when to use, when not to use, alternatives, cost characteristics, validation behavior, pairing with emem_verify_receipt, and provides an example. Since an output schema exists, the absence of return-value details is acceptable. There are no significant gaps for an agent to misuse this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% coverage with descriptions for all four parameters, so the baseline is 3. The description adds value with a concrete example argument set and clarifies how the parameters compose into the token structure. It also mentions the validation constraint on components. It doesn't deeply expand each parameter beyond the schema, but it reinforces and exemplified them well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb and resource: 'Mint a citation handle... that any agent or LLM resolves to the byte-identical signed object.' It clearly distinguishes from siblings by naming emem_entity and emem_memory_bundle as alternatives for different use cases, so the agent knows exactly what this tool does and how it differs.

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

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

The 'When to use' section is explicit and detailed: 'Call when the agent wants a single rebindable string to cite a place plus an attested fact...' It also provides alternative tools for objects (emem_entity) and many facts (emem_memory_bundle), plus a strong when-not-to-use warning: 'wrong tool for carrying a set.' This gives clear decision rules.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds substantial context: response fields at TOP level, explicit null semantics for absence/dimensionless values, the precision caveat for value_verbatim, typed 404 behavior, and the stable fact_url. This is far 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.

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

Although the description is long, it is densely informative and well-structured: purpose, response semantics, when-to-use, edge cases (null, precision), error handling, and an example. No filler; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description covers the full context: response shape, null handling, precision loss, error codes, fallback routes, and a worked example. It leaves no important gap for an agent selecting or invoking this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema describes the single token parameter with 100% coverage, so baseline is 3. The description adds a concrete example argument, explains the token format components (cell64, fact_cid), and details how the parameter is parsed and what response semantics follow, enriching the schema description meaningfully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'Parse a emem:fact:... citation handle and return the reading it cites' with a specific verb and resource. It also contrasts with manually chaining GET /v1/facts/<cid>, distinguishing it from sibling tools like emem_memory_token.

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

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

The description provides an explicit 'When to use' section: 'Call when an agent receives a memory_token from another agent... and wants the value behind it.' It also gives fallback advice for 404s (try /v1/fetch or a mirror). However, it does not explicitly name sibling alternatives for when not to use, so it falls just short of a 5.

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

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

The description goes well beyond annotations by detailing auto-materialization, the fact_cid semantics (not a fingerprint, responder-specific), digest coverage, the deterministic/provenance filters, scoping behavior, and the materialize_notes response field. This is rich, non-obvious behavioral context.

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

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

The description is quite long but well-structured with clear sections ('When to use', 'IMPORTANT', example), and it front-loads the core purpose. Every sentence earns its place given the tool's complexity, though it could be trimmed slightly without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter tool with an output schema, the description covers all critical contextual aspects: return behavior (materialize_notes), error conditions (in schema but explained elsewhere), scope rules, temporal bounds, and response expansion options. It leaves no obvious gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the interaction of deterministic with provenance, the 'IMPORTANT' note about band materializers enabling recall of any cell, and the example arguments which illustrate real parameter combinations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Read the signed facts at a canonical address (cell64)') and its resource, while also noting the auto-materialization behavior. It distinguishes itself from siblings by explicitly referencing emem_entity for crossing responders, and the title and description align.

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

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

Provides explicit 'When to use' guidance: 'Call after emem_locate (or with a known cell64)'. It also contrasts with alternatives ('use emem_entity for identity that crosses responders') and explains the memory algebra semantics ('ensure(cell, bands), not get').

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

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

The description goes beyond the annotations by explaining key behaviors: the endpoint advertises only the core loop by default, tool absence from a list does not mean absence from the server, name short-circuits and ignores other arguments, and unknown names return did_you_mean rather than an error. These are important non-obvious traits that help avoid misuse.

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

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

The description is longer than typical but well-structured with clear sections ('When to use', 'Example arguments') and every sentence carries meaningful behavioral or usage nuance. It's dense but not bloated, though some redundancy with the schema could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description thoroughly explains what returns are expected (working loop, grouped tools, one-line triggers, full schema with name). It also covers edge cases like the did_you_mean response and tier behavior, making the tool effectively self-documenting.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter already has a detailed description, including enums and nuances (e.g., name's short-circuit behavior, category not being a safety filter). The description adds little beyond summarizing which argument to use when, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is a map of emem's tool surface, returning the working loop and all other tools grouped by the question they answer. It distinguishes itself from siblings by being the discovery tool, and explicitly names emem_ask as an alternative for one-shot answers.

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

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

The description provides explicit guidance: 'Call this FIRST when you do not know which emem tool answers the question, or when you need a capability you cannot see in your tool list.' It also explains when to use q, name, or no arguments, and notes alternatives like reconnecting to /mcp/full or using emem_ask.

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

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

Beyond the read-only and idempotent hints, the description discloses crucial behavioral details: the byte-for-byte verification rule, preimage_version handling (v2/v1/absent), the distinction between reshaping and tampering with specific failure reasons, the 200-with-valid:false behavior for bad signatures versus 4xx, and the effect of omitting merkle_proof or preimage_version. This richness significantly exceeds 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.

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

The description is long but well-structured with clear paragraphs and a logical flow from purpose to usage to example. While some points are repeated (e.g., byte-for-byte warning appears twice), each section adds substantial value, and the length is justified by the complexity of the verification semantics. It is slightly verbose but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This tool has no output schema, so the description must explain return values, and it does: it lists all seven fields in the response object. It also covers failure modes, edge cases (omitted fields), the effect of optional parameters, and even includes an example. For a complex tool with nested objects and no output schema, the description is outstandingly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema already covers all parameters, the description adds critical semantics: the two accepted spellings for signature and pubkey, the prohibition on omitting merkle_proof, the advisory nature of current_responder_epoch, and how the facts parameter behaves with a doctored fact. This goes well beyond the schema descriptions and materially aids correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Verify a signed receipt envelope server-side', which is a specific verb+resource statement that clearly identifies the tool's function. It also details the verification algorithm and distinguishes itself from in-browser verification alternatives, making the purpose unambiguous.

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

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

The description explicitly states when to use this tool: 'Use when the in-browser /verify path is blocked... or when you want a server-side audit of a third-party receipt.' It also provides detailed 'When to use' instructions about passing the receipt exactly as returned. However, it does not explicitly name an alternative tool or provide a 'when not to use' exclusion, so it falls just short of a 5.

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