emem, the verifiable memory protocol for the physical world

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

The annotations already provide readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is handled. The description goes well beyond that: it reveals the server-side locate→recall→algorithm chain, that "missing bands are materialised on demand," that the response is a single envelope with `caveats` naming grid resolution and revisit cadence, that verbose output "fits MCP's 25 KB cap," and that the optional `model` path never replaces the deterministic `answer` (provenance.class = model_output, with named latency 13–22 s). Without reading anything else, the agent is fully aware of what happens server-side, how long it takes to run, and what it will and won't return.

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 (first sentence states the single-shot evidence-backed purpose), has a clearly signposted "When to use" section, and ends with a JSON example — excellent structure for an 11-parameter tool with a complex response envelope. It could be tightened: several sentences (e.g., the `model` and `verbose` behaviors, the alias list, part of the envelope enumeration) repeat what the input schema already documents in comparable detail.

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 this complex — 11 params, an output schema, sibling tools like emem_locate/emem_recall — the description covers the critical context: the decision to call where to call, how to pick among place/cell/lat+lng, the shape of the output envelope, the caveats/inventory return, and the fallback routing behavior. An output schema covers the return-values, so those is not necessarily required here. Remaining gaps are minor (e.g., no mention of auth requirements or rate limits), but the main deficiencies are covered.

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 does add meaning: it says to send the user's question "verbatim" as `q`, gives a concrete example argument mapping, clarifies that `place` only works as an alternative to `cell` (which must come from a prior emem_locate/emem_recall response, relative to lat/lng pairs), and frames disguised response sections ("added ordered stages" via include). It does not however describe the `query`/`question` aliases or add much over the schema for `lat`/`lng`/`include_image`, so the top of the 1–5 range isn't reached.

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 leads with a specific verb+resource: "Single-shot free-text answer about a real-world location, backed by signed satellite/elevation/water/built-up receipts." It then makes the differentiation explicit by naming the server-side chain it runs ("locate → recall → algorithm chain") and by referencing sibling tools emem_locate and emem_recall as sources of `cell`. An agent can tell exactly what this tool does versus geocoding (emem_locate) or raw recall (emem_recall).

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 gives an explicit when-to-use: "Call when the question is about a specific place and the answer should carry its own evidence," plus concrete instruction (send the user's question verbatim as `q` and a location via `place`/`cell`/`lat`+`lng`). It also defines the boundary condition ("A question outside the corpus answers... matched_topic: null with the inventory, so you can route elsewhere rather than guess"). It falls short of 5 because it never explicitly names a sibling as the alternative for out-of-scope questions or says when NOT to call this tool beyond the corpus-boundary case.

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, the description discloses nuanced behaviors: `strict` changes exactly one outcome, JSON numbers lose trailing digits before comparison, and a non-52-character cid is refused as damaged. These are load-bearing edge cases an agent needs to know before calling.

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 every sentence carries operational weight: the primary purpose, the verification workflow, the strict-mode caveats, and a concrete example. It is well-structured with a 'When to use' section and front-loaded core behavior.

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 an output schema present and annotations covering the read-only, idempotent safety profile, the description still fills all practical gaps: return semantics, failure modes, parameter formatting, and pairing guidance. Nothing needed for confident invocation or selection is 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?

Schema coverage is 100%, yet the description adds substantial value beyond it: it explains why `claimed_value` should be sent as a string, how `strict` interacts with numeric respelling, and how bare cids alter the grade. This goes well above the schema's own parameter 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 specific verb and resource: 'Grade a value you are about to emit against the signed fact your citation points at,' and says it returns `matches` and `drift`. It clearly distinguishes this echo-verification step from related tools by naming the verify operation and pairing it with `value_verbatim` from resolve.

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 gives explicit timing and conditions: 'Call immediately before publishing, logging, or handing on any value you took from an emem fact,' and instructs treating a false `matches` as a gate. It also names the companion tool, `value_verbatim`, and explains when a bare cid is appropriate.

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 adds substantial behavioral context beyond annotations. It explains the idempotence (same object mints same entity_cid), the dominance of external IDs (Overture GERS / OSM) in identity, the anchoring mechanism (lat/lng/cell), and the return format (entity_token plus signed receipt). It also clarifies the conceptual boundary (entity is a thing AT a place). None of this contradicts the annotations; it complements 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 relatively long but well-structured, starting with a clear purpose and then layering usage guidance and examples. The 'When to use' and 'Pick the sibling' sections are front-loaded after the opening paragraph. While every sentence earns its place, it is denser than strictly necessary; a slightly tighter version would merit a 5.

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 8 parameters, nested objects, and no output schema, the description covers all essential aspects: what the tool does, when to use it, how it behaves (idempotent, anchor-driven), what it returns (entity_token + signed receipt), and parameter semantics (anchoring, external IDs). Nothing critical is missing for an agent to call it 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 the schema already documents all parameters. The description adds meaningful guidance: it explains the anchor requirement (place OR cell OR lat+lng) and that external_ids drive convergence and override geocoder-derived values. It also provides a concrete example argument set. This goes beyond the schema, though it does not exhaustively annotate every parameter, so a 4 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 states a specific verb (mint/get) and resource (canonical object identity) and explains the core behavior: content-addressed identity that resolves consistently. It explicitly distinguishes itself from siblings (emem_entity_resolve, emem_entity_link, emem_recall, emem_locate) by naming what it is not. The purpose is unambiguous and the agent can tell it apart without opening schemas.

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 that tells the agent to call when referencing a THING and wanting a stable handle, and it names the sibling alternatives with the conditions that select them (emem_entity_resolve for fuzzy search, emem_entity_link for asserting two spellings). It also gives clear negative guidance: not for observations (emem_recall) or naming a place (emem_locate). No ambiguity remains about when to invoke this tool.

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 only say this is a non-destructive, idempotent, open-world write; the description goes well beyond with the important traits: signed and attributed to your key, shared-space effect on other agents' resolution, per-key rate limiting, agreement weighted by independent keys, append-only recording, and the guarantee that a dispute deletes nothing.

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?

Front-loaded with the core claim before the 'When to use' block and example; every sentence carries information about behavior or selection. The all-caps emphasis and dense clauses make it slightly heavier than needed, but nothing is wasted.

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 5-parameter, nested-object, no-output-schema write tool, the description covers attribution, rate limits, dispute handling, and external id binding well. It stops short of describing the success/return behavior or what happens if an alias conflicts, which is the only remaining 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the stance semantics and their consequence (a dispute is shown beside the binding it answers), names the external id systems (GERS/OSM/Wikidata), and provides a worked example using entity_token and alias.

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?

States a precise verb and resource: recording a signed, attributed claim that a label or external id denotes an existing object, plus the dispute variant. An agent can tell this is a write-side attestation tool rather than a read-side resolver like emem_entity_resolve without opening the schema.

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' block names the triggering conditions (vouching two phrasings denote one object, attaching an authoritative external id) and when to choose stance 'disputes' (another key's binding is wrong), plus that mere corroboration is useful. It does not explicitly point to a sibling for the read path, so it stops just short of full routing 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes further by disclosing the ranking rule, the candidate fields returned (asserted_by, disputed_by, independent_attesters, corroboration enum), the contested flag behavior, and the data-provenance caveat that alias text is other agents' data. With no output schema, this return-shape disclosure is doing real work.

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?

Front-loaded with the core purpose, then return semantics, then usage, then an example. Dense but each sentence carries information; the enum listing and field names are slightly list-heavy but justified given no output schema.

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 five-param, output-schema-less resolver, the description covers purpose, return shape, ranking semantics, usage ordering, and the corroboration follow-up. Nothing an agent needs to call it correctly or interpret results is 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?

Schema coverage is 100%, so the baseline is 3, and the description adds semantic routing above that: which of text/near/token to use and for what purpose ('text for candidates, near to narrow by place, or an emem:entity: token to dereference'), plus a worked example argument combining text and near. It stops short of explaining k or label, which the schema already covers.

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?

States a specific verb and resource ('Find the objects agents have bound a phrasing to') and immediately differentiates the ranking semantics ('ranked by INDEPENDENT corroboration, never arrival order'). An agent can distinguish this resolver from siblings like emem_entity_link and emem_find_similar without opening a schema.

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' block gives explicit sequencing ('Call BEFORE minting and before citing: resolve first, mint only if nothing matches') and names the complementary action and tool (corroborate a single_key binding with emem_entity_link). When, why, and the alternative are all present.

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 adds rich behavioral context far beyond the annotations: mode tradeoffs (exact vs approximate vs rerank), the meaning of an empty result under open-world semantics, the materialisation behavior for a missing key vector, and the Lance-index bypass for scope/as-of filters. It also clarifies that filter-relevant cells with no fact are dropped rather than treated as false. This aligns with and enriches the openWorldHint/idempotentHint 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 dense but well organized: it front-loads the core return contract, then explains scoring modes, k bounds, open-world semantics, when to use, and an example. The occasional redundancy with the schema is minor and serves narrative clarity rather than padding.

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 no output schema, the description fully explains the return shape, the meaning of missing neighbours, the side-effect of materialising the key's band, mode/band selection, and the consequences of scope/as_of/filter. An agent has everything needed to decide, invoke, and interpret the result 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?

Although schema coverage is 100%, the description adds substantial parameter meaning: mode-specific precision/performance tradeoffs, band naming and dimensionality, the effect of scope and as_of on the ANN fast-path, and the semantic behavior of the filter. This goes well beyond the schema's own property 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 specific operation (k-NN over the corpus) with a concrete resource (cell embedding or inline vector) and exact outputs (ordered neighbours with cell64, score, band, and signed receipt). It also disambiguates by giving canonical user phrasings ('find places like X', 'where else looks like this'), making it clearly distinct from sibling memory/entity tools.

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 has an explicit 'When to use' section with concrete query phrasings and example arguments, plus guidance on choosing bands and modes. It does not name specific sibling tools to avoid, nor give explicit 'when not to use' conditions, so it stops just short of full routing 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, idempotentHint, destructiveHint, and openWorldHint. The description adds crucial behavioral nuance: nothing is blocked (advisory), a citation not held is never a denial, a check that reads nothing still answers allow, and unrecognized shape values fall back to native. These go well beyond the annotations and materially change how an agent interprets results.

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 every sentence earns its place. It opens with the core purpose, then usage guidance, then an example. It is structured with clear paragraphs and inline code for the verdict format and codes. No fluff, and the density is appropriate for a tool with subtle behavior.

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 4-parameter tool with an output schema and multiple siblings, the description covers purpose, usage, alternatives, behavior, parameter nuances, and an example. It even references the verify operation with a documentation link. Nothing an agent needs to call this correctly is 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?

Schema coverage is 100% with rich descriptions, so the baseline is 3. The description adds value beyond the schema: for 'shape' it explains the fallback behavior and the importance of matching citations_found; for 'texts' it advises sending only the smallest relevant input; for 'claim_gating' it explains the resulting deny code and fix. This extra context justifies a 4 rather than a 3.

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 ('Run'), the resource (emem-guard's policy pipeline), and the exact outcome (finds citations, resolves them, returns allow/deny with codes). It distinguishes itself from siblings by naming the enforcement alternative (emem_guard_selfhost) and from other verification tools like emem_verify_receipt via the corpus-scoped, advisory nature.

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' paragraph gives explicit contexts: check drafts before asserting, check tool results before reasoning, and catch unresolvable citations while still fixable. It also says when NOT to use it (for enforcement, use emem_guard_selfhost) and explains the shape parameter for external payloads. This is complete and actionable.

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?

While annotations already provide idempotentHint=true and destructiveHint=false, the description adds substantial behavioral detail beyond them: the tagged-union semantics, that the plan is executed in the same call, that fields belonging to another intent are ignored, and that an unknown or missing type returns a structured needs_intent_type envelope instead of a hard error. No contradiction with the annotations is present.

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 appropriately so for a 14-parameter tagged union with seven modes. It is front-loaded with the core concept, then organized into a compact table, a routing section, and an example. Every section contributes actionable information rather than 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?

Despite having no output schema, the description covers expected outputs per intent in the answers column, explains error-recovery behavior for invalid types, notes how to obtain valid tslots, and provides a runnable example. This is sufficient for an agent to select the tool and construct a correct call for any of the seven intents.

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 already provides 100% field coverage with detailed per-parameter descriptions, so the baseline is 3. The description adds value on top by mapping each type to its required versus optional fields, clarifying that only the fields 'its row needs' should be sent, and giving a concrete example. It does not substantially restructure what the schema already says, but it helps the agent navigate the union.

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 purpose: 'Say what you want in one typed object and get the answer, without choosing a primitive.' It then enumerates seven distinct intents in a table, each with required fields and expected answers, making it easy to differentiate from sibling primitives like emem_recall and 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?

An explicit 'When to use' section gives both the positive condition ('Call when the question maps onto one of the seven rows above') and the negative routing with named alternatives ('Otherwise go direct: a band at a cell is emem_recall, a region is emem_recall_polygon, a free-text place question is emem_ask'). Additional guidance covers tslot semantics and how to handle tools not in the core list.

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, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the canonical/vendor-neutral nature of the address, the precedence rule ('coordinates win when both arrive'), the alias acceptance, and the '_unrecognised_arguments' behavior for typos. It doesn't describe the full return shape, but the description explicitly mentions the key return fields (live_bands_by_topic, algorithms_for_topic, declared_but_no_materializer_at_this_responder). This is strong behavioral disclosure.

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 dense but well-organized: purpose first, then return-value summary, then disambiguation, then parameter semantics, then when-to-use, then example. Every sentence earns its place, though the opening sentence is long and packs many concepts. The 'When to use' section is clearly front-loaded after the core purpose. 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?

For a read-only, idempotent tool with 100% schema coverage and no output schema, the description is quite complete. It explains the core return fields, the input alternatives, the precedence rule, and the error behavior for unrecognized arguments. The only minor gap is that it doesn't describe the exact structure of the cell64 or the full response envelope, but the description explicitly names the key return fields. Given the tool's complexity and the absence of an output schema, this is strong coverage.

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 description coverage is 100%, so the schema already documents all 6 parameters. The description adds meaning beyond the schema by explaining the alias relationship ('q, query and name are all accepted spellings of place'), the precedence rule, and the typo-handling behavior. It also gives a concrete example argument. This exceeds the baseline 3 for full schema coverage.

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 ('Mint the canonical, vendor-neutral address (cell64)') and resource ('real-world place'), and explicitly distinguishes itself from emem_entity ('For a first-class OBJECT identity... use emem_entity'). It also names the sibling emem_ask for a different use case. This is a clear, specific purpose that an agent can act on.

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 gives explicit when-to-use guidance: 'Call when the input names a real-world place and the next step needs its cell64, or wants to know which bands exist there before recalling.' It also names alternatives: emem_entity for object identity, emem_ask for a packaged answer. It even explains the coordinate-vs-place precedence rule. 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?

The description discloses the signing/responder behavior, offline verifiability via /v1/verify_receipt, the auto-materialize recall path, O(1) token size with N/256 round trips, and `members`/`resolved` output so partial resolution is visible. This goes well beyond the minimal annotations and does not contradict 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 operation, then gives a clear 'When to use' section, constraints, and a representative example. The 'Memory algebra: the merge operation' link is somewhat incidental and unexplained, keeping it from being perfectly economical.

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?

Even without an output schema, the agent learns what the call returns or produces: a bundle_token, a signed receipt covering fact_cids and cells, and `members`/`resolved` fields. Limits, verification path, distinction from alternatives, and an example are all present, so the tool can be invoked correctly without further context.

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 description coverage is 100%, and the schema already documents `scope`, `purpose`, `triples`, and `fact_cids` including exclusivity, formats, and limits. The description's example arguments are handy but mostly restate schema semantics rather than adding new parameter meaning, so the high-coverage baseline applies.

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 names a specific verb and resource: compose (cell, band, tslot?) triples into one signed envelope and produce an `emem:bundle:<bundle_cid>` token. It also distinguishes itself from the sibling `emem_memory_token` single-fact composer, so an agent can select it without opening schemas.

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 says to call this when multiple facts should be cited as one handle and to prefer it over N separate `emem_memory_token` composers when the citation is conceptually one thing. The 256-triple cap and round-trip planning note provide actionable boundary conditions.

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 read-only and idempotent behavior, so credit goes beyond that use: the description adds the important default-scope caveat ('by default only two DISTINCT attesters'), the meaning of a zero result, severity formulas per band kind, and the existence of disagreement_scope/citations in results. This is valuable context beyond the annotation fields.

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 text is front-loaded with the core purpose, organized into a function—definition block and a 'When to use' block, and ends with a concrete example. It is long but each section carries meaningful instructions; no real filler, though some schema repetition exists.

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 explains what records return (severity, citations, disagreement_scope), specifies severity formula variations, and it refers to what is not covered by a zero. It is sufficiently complete for an agent to know when to call and what to expect.

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 most parameters already have long descriptions. The description adds usable context such as 'Narrow with cell_prefix and band' and the single-responder purpose of include_same_attester_sources, plus an example, so it does exceed the schema alone, even if some details are repeated.

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 that this tool surfaces corpus self-disagreement with severity scores and citations for competing values, and explicitly contrasts itself with a 'confident single answer' so it is distinguishable from sibling query tools like emem_ask or emem_recall.

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?

It has an explicit 'When to use' paragraph with example questions and gives concrete guidance on narrowing with cell_prefix/band and on the include_same_attester_sources flag for single-responder deployments. It does not explicitly name an alternative tool for the opposite single-answer case, though it implies it via 'the opposite of a confident single answer'.

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=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it details validation logic (non-empty, no `:` separator), the resolution semantics (byte-identical signed object), and error behavior (409 on date mismatch). While it doesn't explicitly restate read-only status, it complements annotations with operational details, earning a 4.

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 purpose is front-loaded in the first sentence, followed by usage guidance, a detailed comparison with bundles, and an example. The cost analysis paragraph is longer than strictly necessary but is well-structured and provides decision-relevant data. No superfluous fluff; every sentence serves a function. Slightly long but appropriately organized for an agent to parse.

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 an output schema present (context signal says it has one), the description does not need to explain return values. It covers the input purpose, when to use, trade-offs vs. alternatives, validation constraints, and gives a concrete example. For an agent deciding whether to call this tool and how to invoke it correctly, nothing essential is missing. 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 description coverage is 100% (all 4 parameters have descriptions). The description adds an illustrative example with real-looking values and explains the validation rule that both components must be free of `:`, which is not fully captured in the schema (the pattern for `cell` exists, but `fact_cid` has no such constraint). This supplements the schema notations and provides meaning beyond the basic property descriptions, so a 4 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 states a specific output: it mints a citation handle in the exact format `emem:fact:<cell64>:<fact_cid>` (or `:<state_cid>`). It distinguishes itself from the sibling `emem_memory_bundle` by explicitly noting that individual tokens are for citing ONE fact, while bundles handle many facts. The verb 'Mint' and resource 'citation handle' are clear and 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?

Provides explicit when-to-use: 'Call when you want one rebindable string to cite a place plus an attested fact across messages, threads, agents or tools.' It also states when NOT to use it: 'FOR MANY FACTS USE emem_memory_bundle INSTEAD' with a quantitative comparison of token costs and context overhead. It even recommends pairing with `emem_echo_verify` before publishing. This is model-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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the response structure (value, unit, band, kind at top level, full signed fact), the semantics of explicit nulls, the typed 404, and the availability of a stable fact_url. This goes well beyond the annotations and informs the agent of expected outcomes and error handling.

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 strictly necessary but is well-structured: the first sentence states the core purpose, followed by response details, a 'When to use' section, and an example. It is front-loaded with the main action and uses clear sections. While some content (e.g., the doc URL) could be trimmed, the structure makes it easy to scan and the length is justified by the explanatory value.

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 having no output schema, the description thoroughly explains the response format, including top-level fields (value, unit, band, kind) and the presence of the full signed fact and fact_url. It also covers null semantics and the typed 404 with fallback options. For a single-parameter read-only tool with annotations covering safety, this is complete—nothing an agent needs to call it correctly is 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 has 100% description coverage for the single parameter 'token', which already defines it as a 'citation handle to dereference.' The description repeats the format and gives an example argument, but it does not add new semantic meaning to the parameter itself. The extra details about response fields are more about output than input, so the description adds limited value beyond the schema, warranting the baseline score of 3.

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 and resource: 'Parse a `emem:fact:<cell64>:<fact_cid>` citation handle and return the reading it cites.' It clearly distinguishes from manual string-splitting and chaining GET /v1/facts/<cid>, and names the operation 'resolve' in memory algebra. The purpose is unambiguous and differentiated from siblings 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 contains an explicit 'When to use' section: 'Call when you hold a memory_token from another agent or an earlier turn and want the value behind it.' It also provides a specific nuance for scalar quotes (value_verbatim to preserve precision) and an alternative for a typed 404: 'try /v1/fetch, or resolve at a mirror.' These are concrete usage conditions and fallbacks, leaving no room for guesswork.

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 the annotations. It explains that a miss triggers fetch/sign/persist, that fact_cids are exact bytes rather than fingerprints, that receipts bind scope, and that include options affect response contents. It also discloses bi-temporal boundaries and the advisory freshness block. This is far richer than the readOnlyHint=false and openWorldHint=true 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?

The description is long (about 1000 words) but front-loaded: the first sentence states purpose and behavior, followed by nuanced semantics听闻, usage guidance, and example. The structure is clear, though a few sentences repeat schema content and could be trimmed without loss.

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?

All core behaviors are covered: materialization, fact identity, responder-scoped resolution, deterministic/provenance filtering, include expansions, scope, bi-temporal bounds, and example arguments. The output schema handles return-value details, so nothing an agent needs to call or interpret this tool is 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?

Schema description coverage is 100%, so baseline is 3. The description adds an example argument set and briefly restates deterministic's meaning, but does not introduce new parameter semantics beyond the schema. It offers a concrete usage illustration, but the schema already documents every parameter fully.

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 leads with a specific verb and resource: 'Read the signed facts at a canonical address (cell64)' and immediately adds the key behavior 'auto-materializes on a miss'. It distinguishes itself from emem_entity by explicitly noting 'use emem_entity for identity that crosses responders', and clarifies the semantic as ensure rather than get.

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?

It gives an explicit 'When to use' section: 'Call after emem_locate, or with a known cell64 or place name.' It also names an alternative for a specific condition ('use emem_entity for identity that crosses responders') and explains the materialization trigger with a practical example ('pass bands: [<band>]').

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, the description discloses that hosts strip `_meta`, that a visible list of 18 tools is only a curated subset of 114, that all catalogued tools remain callable via tools/call, and that `name` short-circuits other arguments. These are behavioral traits that the annotations alone do not convey. No contradiction with readOnlyHint, idempotentHint, or destructiveHint is present.

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 densely packed and well structured: identity and role come first, then the working-loop ordering, grouping logic, retrieval behavior, and a dedicated "When to use" section. The all-caps subset warning and example arguments each carry operational information that is not redundant with the schema.

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 zero-required-parameter introspection tool with a rich schema and no output schema, the description covers everything needed: no-arg behavior, q/name entry points, tier filtering, the return shape as a question-grouped map with one-line triggers, and the fallback path via tools/call. An agent can decide whether and how to call this tool without further information.

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% descriptive coverage of all six parameters, so the baseline is 3. The description adds the no-arguments "whole map" behavior and a concrete runnable example ({"q":"ndvi"}), which are useful, but it does not need to compensate for a schema gap. It adds meaning without being the primary source of parameter understanding.

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 names the tool as "the map of emem's tool surface" and "the only tool you need to find the rest," making its catalog-discovery role explicit. It also distinguishes itself from siblings such as emem_ask, which "answers in one shot without picking a primitive." This is a specific verb-plus-resource description, not a tautology or vague label.

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" block instructing the agent to call this tool FIRST when it does not know which tool answers or needs a capability absent from its current list. It also names alternatives: /mcp/full for registering the full catalog and emem_ask for one-shot answers, plus the `name` parameter for when the agent already knows the exact tool.

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 declare readOnly/idempotent/non-destructive, and the description adds critical behavioral detail beyond that: byte-for-byte binding, v2 inclusion proof invalidation on reshaping, the two omissions that produce false forgery rather than a 400, and bad signatures returning 200 with valid:false. 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?

Long but dense and front-loaded: the first sentence gives the operation and output contract, and each subsequent paragraph carries a distinct warning, routing rule, or example note. No filler; the length is appropriate for a security-critical verifier with subtle failure modes.

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?

No output schema exists, so the description supplies the full return shape and valid:false semantics. It covers all four parameters, the critical false-forgery cases, the alternative token-resolution path, and even how to obtain a runnable example. Nothing an agent needs to invoke this correctly is 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?

Schema coverage is 100%, so the baseline is 3, but the description adds substantial semantics beyond the schema: consequences of omitting facts, exact accepted spellings for signature/pubkey fields, the merkle_proof and preimage_version failure modes, and the advisory nature of current_responder_epoch. This lifts it well 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?

States a specific verb and resource: 'Verify a signed receipt envelope server-side', then enumerates the exact verification steps and return fields. It also distinguishes itself from the sibling emem_memory_token_resolve by explicitly saying a token is not a receipt and from the in-browser /verify path, so an agent can select it correctly.

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?

Contains an explicit 'When to use' section naming the in-browser /verify path and server-side audit use cases, plus an explicit when-not: if all you hold is an emem:fact token, call emem_memory_token_resolve first. This gives clear routing among alternatives.

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?

Goes well beyond annotations: it explains the readOnlyHint=false flag by disclosing that cell handles can MATERIALIZE a missing band (fetched upstream, signed, persisted), while fact handles write nothing. It also reveals exact-decimal quoting, never re-rendering, and inline oversize-body behavior. 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?

Front-loaded with the core purpose, then compactly covers usage, side effects, and an example. Every sentence earns its place; no filler or repetition of the title or schema. The length is justified by the tool's behavioral 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?

With an output schema present, the description appropriately focuses on selection and invocation semantics. It covers the id format, the effect of each handle type, when to call it, what to quote, and how oversize bodies are reported. Nothing needed for correct invocation is 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?

Even though schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains the three accepted id forms and the behavioral difference between fact and cell handles, including the write path. This directly helps an agent choose the correct argument form and anticipate side effects.

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?

States a specific verb ('Dereference'), the exact resource (an id from search), and the returned components (reading, signed body, URL, metadata). It clearly differentiates itself from search (which lists results) and from emem_recall/emem_echo_verify by naming them and describing its distinct role.

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?

Explicitly says when to call it: 'Call on each result you intend to cite, before quoting the number.' It also gives the alternative context by distinguishing fact handles (writes nothing) from cell handles (materializes like emem_recall) and references emem_echo_verify for verification.

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 the annotations by explaining why readOnlyHint is false: on a cold cell it materializes a missing band, 'fetched upstream, signed, persisted.' It also discloses the wire cap and the sentinel final entry naming the cell and TRUE total, which are not visible in 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 front-loaded with the core behaviorstalemate, then usage guidance, then an example, with no filler. Every sentence contributes either output shape, input semantics, behavioral caveats, or alternative routing.

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 one simple parameter, a rich output schema, and annotations, the description supplies all remaining operational context: when to call it, how to prefer it over emem_ask, what the output looks like, and the important cold-cell materialization side effect. Nothing an agent needs to invoke it correctly is 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?

Schema coverage is 100%, so the baseline is a 3, but the description adds an example argument and clarifies behavioral distinctions between the accepted query forms, notably that a citation handle 'returns the one fact it cites.' This enhances what the schema alone provides.

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 and resource: 'Search emem's signed corpus and return results shaped as citations,' and it precisely enumerates the output shape (id, title, url). It also distinguishes itself from siblings by positioning results as citable sources that fetch can expand and emem_ask can synthesize.

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?

It explicitly states when to use the tool: 'Call first when a question is about a place and the answer must be citable.' It also names the alternative: 'For a synthesised answer in one call, use emem_ask instead,' and explains the handle case that returns a single fact. This gives an agent clear routing guidance.

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