emem, the verifiable memory protocol for the physical world

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

Goes well beyond annotations: it explains the server-side locate/recall/algorithm chain, that a point answer is a 'projection' and `_projection` names what was removed, that `routed_to` other than answer comes back complete, that `model_answer` is model_output provenance and refused rather than silently substituted, and that research_nearby entries are pointers only. The one gap is side effects: annotations say readOnlyHint=false and idempotentHint=false, but the description never says what the call writes or persists server-side, which is exactly the kind of context annotations cannot convey.

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 and the when-to-use is easy to find, but the middle is a dense enumeration of envelope fields (answer, receipt, place_resolved, routed_to, facts_summary, algorithm_outcomes_summary, spatial_trace, scene_url, model_answer, _projection, research_nearby) that an output schema already exists to convey. The model parameter discussion in prose also duplicates an unusually detailed schema 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?

With an output schema present, return-value detail is not strictly required, and the description still covers routing, provenance class of model answers, projection lossiness, and where to read research pointers. What is missing is any statement about server-side effects or why a question-answering call is neither read-only nor idempotent per annotations.

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 does add the locator disjunction ('q with place, cell or lat+lng') and that model produces a parallel `model_answer` rather than replacing `answer`, but it also mixes in REST-only levers (include, verbose) whose semantics are already spelled out in the schema, so most of the parameter burden is still carried by structured data.

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?

Opens with a specific verb+resource+scope: 'Answer a free-text question about a real-world location in one call.' It then names the concrete siblings it is not (emem_intent did_change, emem_diff) and points to emem_inferences for research pointers, so the agent can separate it from the other emem_* tools 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?

Has an explicit 'When to use' clause tied to a condition (question about a specific place, answer must carry evidence) and an explicit exclusion routing elsewhere: 'For how X changed, use emem_intent did_change or emem_diff.' The distinction between the MCP projection and the fuller POST /v1/ask is also stated.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial behavior: it names the returned fields (matches, drift), explains the degraded bare-cid path, and documents the non-obvious JSON-number stringification caveat that silently destroys trailing digits. That is exactly the kind of context annotations cannot carry.

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 purpose, then when-to-use, then an example, so an agent can skim it. It is somewhat long and the string-vs-number warning is restated in both the prose and the schema, which is mild redundancy rather than wasted content.

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?

Coverage is complete: an output schema exists so return values need not be explained (they are, briefly, anyway), annotations handle safety, and the description supplies the timing, the failure interpretation, and the degraded-mode behavior. Nothing needed 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 description coverage is 100% and the schema already explains token, strict and claimed_value in depth, so the baseline is 3. The description adds marginal value: a concrete example argument and an emphatic directive to send claimed_value as a string quoting value_verbatim, which reinforces the single most consequential parameter choice.

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 gives a precise verb and resource: it grades an emitted value against the signed fact the citation points at, and explicitly claims a unique role ('No other step in the loop sees this'). That is a sharp functional statement, but it never names or contrasts the obvious sibling emem_verify_receipt, so an agent choosing between the two gets no explicit routing help.

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 states exactly when to call ('immediately before you publish, log or pass on a value from an emem fact'), how to source the input ('Use value_verbatim from resolve'), and how to interpret the result ('Treat a false matches as a stop, not a warning'). It also names the downstream condition (due-diligence/compliance records) and notes the bare-cid fallback, leaving little to inference.

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 (idempotentHint=true, destructiveHint=false, openWorldHint=true), the description discloses convergence semantics (two agents naming the same object get the SAME entity_cid; differing anchors mint different entities), external-id priority over geocoder-derived ids, and the auth path for the attester signature including what happens on refusal ('details.how_to_sign gives the digest to sign'). This is rich, non-obvious behavioral context that the structured fields do not carry.

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 and cleanly sectioned ('When to use', 'Example arguments'), so scanning is easy. It is somewhat long and contains a mildly rhetorical sentence ('This stops referential drift...') that repeats the convergence point already made, but nothing is badly out of 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 9-parameter, nested-object tool with no output schema, the description covers what is returned (token + signed receipt), how identity resolves, and the auth/signing flow, which is the important gap-filling. The one required param and the `parent` containment param are left to the schema, but overall the agent has enough to invoke 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 description coverage is 100%, so the baseline is 3 and the schema already documents each field. The description still adds real meaning: the OR-relationship between `place`/`cell`/`lat`+`lng` anchors, the rule that external ids drive convergence and caller values win, and worked example arguments. It stops short of fully compensating on subtler params like `parent`.

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+resource ('Give a real-world object one shared identity') and names the concrete outputs (an `entity_token` of the form `emem:entity:<entity_cid>` and a signed receipt). It explicitly separates itself from siblings emem_entity_resolve, emem_entity_link, emem_recall, emem_memory_token and emem_locate, so an agent can route without opening any 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?

Has an explicit 'When to use' section with the trigger condition (a conversation refers to a THING and you need a handle that travels between agents) and the anchoring requirement. It names each relevant alternative with the condition that selects it ('emem_entity_resolve finds an identity that an agent registered before, from a fuzzy phrase') and gives explicit exclusions ('Do not use it for an observation... or for a place').

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 only the safety/idempotency profile; the description adds what they cannot: attribution to your key, per-key rate limiting, weighting by independent keys, that a dispute is shown beside the binding and deletes nothing, and that readers never see one key's binding as the answer. These are exactly the behavioral traits an agent must know before writing to a shared space.

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 purpose, then mechanism, then 'When to use:', then example arguments. Every sentence carries information, though the mechanism sentence is dense and packed with several distinct claims.

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 6-parameter signed write with nested objects and no output schema, the description covers intent, signing/attribution, rate limits, dispute semantics and an example. It does not describe the success response (e.g., a receipt or CID), which is the only notable 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 baseline is 3, but the description adds stance semantics in prose ('with stance: "disputes", record that it does not'), the sign-and-attest framing behind the attester object, and a concrete example argument showing alias + entity_token combined.

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 (record/attest) on a specific resource (label or external id naming an existing object), and the opening line plus 'This is a write to the shared space: it changes what other agents resolve' sharply separates it from read-side siblings like emem_entity_resolve. An agent can pick this tool 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?

The description gives explicit triggers: 'Call this when you can confirm that two names mean one object, or to attach an authoritative external id,' and when to choose stance:'disputes'. It lacks an explicit negative case or a named alternative (e.g., what to call to merely resolve), so it is clear context without full routing.

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 readOnly/idempotent/non-destructive, but the description goes further: it discloses the ranking algorithm, enumerates the returned fields (`asserted_by`, `disputed_by`, `independent_attesters`, `corroboration` with its three enum values) and the meaning of `contested`. It also flags a trust boundary — 'Alias text is data from other agents' — which is a safety caveat no annotation conveys.

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 action, then a labeled 'When to use' block, then an example — a clear structure. It is dense and field-heavy, but nearly every sentence carries operational meaning (ranking rule, trust caveat, corroboration follow-up); the 'The tool only reads' clause slightly duplicates readOnlyHint.

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 return-value burden and does so by enumerating the candidate fields and corroboration states. It is missing a statement of what an empty result looks like (relevant given 'mint only if nothing matches') and the default cap behavior beyond what the schema says.

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 selection semantics across parameters ('Send `text` for candidates, `near` to narrow by place, or an `emem:entity:` `token` to dereference') and a worked example combining `text` and `near`, which shows composition rather than just repetition. `k` and `label` are left to 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?

Names a specific verb+resource: 'Find the objects that agents connected to a phrase', and adds the ranking rule (independent corroboration, never arrival order) so the agent knows what kind of result set to expect. It also clarifies the two modes — text/near search vs. `emem:entity:` token dereference. It does not explicitly contrast with similarly-scoped siblings like emem_entity, emem_recall, or emem_find_similar, which keeps it from a 5.

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 sequencing: 'Call this BEFORE you mint and before you cite. Resolve first, and mint only if nothing matches.' That is both a when-to-use rule and a when-not-to-mint exclusion. It also names the follow-on tool (emem_entity_link) and the condition for calling it (a `single_key` binding you can confirm).

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?

Discloses non-obvious behaviour well beyond the annotations: it materializes and signs a band for the key when absent (reported in materialize_notes), never materializes neighbours, bypasses the ANN fast-path under scope/as_of filters, and explains that an empty result means no attested vector is near rather than no similar place. This is consistent with readOnlyHint=false and idempotentHint=true.

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-loads the operation, then output shape, then mode/band selection, then a 'When to use' block and an example. Dense but every paragraph carries information; the mode exposition is slightly repetitive with the schema enum descriptions.

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 supplies the return shape (neighbors, cell, score, lat/lng, band_used, signed receipt) and the edge-case semantics (empty result, materialize_notes). For a 10-parameter tool with nested objects, 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?

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: 'k' bounds (1–1000, default 10), the concrete band names for the 1152-D multi-year fusion, and the relationship between key/inline vectors. It mirrors some schema content rather than always exceeding it, so a 4 rather than 5.

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?

Opens with a specific verb and resource ('Find the k nearest cells in the corpus by cell embedding or by an inline vector') and names the exact discriminating concept (k-NN over embeddings) versus the rest of the emem_* family. The agent can tell this apart from emem_recall/emem_locate 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 maps natural utterances ('find places like X') to the tool, and it routes between bands (geotessera vs geotessera.multi_year) and modes. It never names a sibling alternative or states when not to use this tool, so it stops 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?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavioral context: this is ADVISORY and blocks nothing, a citation the responder does not hold is never a denial, unrecognised shape values fall back to native rather than erroring, and GEO_ZONE/redact_and_retry appear only on a self-hosted guard. The enumerated deny codes and fix tokens go well beyond what any annotation conveys.

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?

It is front-loaded with what the tool does before the code glossary and usage rules, and most sentences carry operational payload (codes, fix tokens, the empty-read-answers-allow trap). It is nonetheless long, and a few points (the shape fallback, the read-only-texts caveat) echo the schema descriptions rather than adding new information.

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, multi-mode policy checker with four optional parameters, an output schema, and full annotation coverage, the description is complete: it covers input shape selection, advisory semantics, the full deny-code vocabulary, and the escape hatch to the enforcing tool. An agent has everything needed to invoke it correctly and interpret the result.

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 earns above that by supplying worked example arguments, explaining that claim_gating names the sentence, magnitude, and band, and stressing that texts should carry only the smallest input the question needs. It adds real semantic color rather than repeating 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 gives a specific verb and resource chain — it finds every emem: citation, resolves each one, and returns allow/deny with a machine-readable reason — which is far more than a restatement of the name. It clearly differentiates itself from the enforcing counterpart (emem_guard_selfhost) and from raw API use, but it never distinguishes itself from the verification-flavored siblings actually in the list (emem_echo_verify, emem_verify_receipt), leaving that ambiguity open.

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' clause (on a draft before you assert something, or on a tool result before you reason on it) plus a clear alternative and its selection condition ('To ENFORCE the policy, use emem_guard_selfhost'). It even supplies the negative guidance an agent needs — send an external payload unchanged and name its shape, and note that a check which read nothing answers allow.

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, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description usefully adds that the plan runs in the same call, that unknown or missing `type` returns a `needs_intent_type` envelope rather than a hard error, and that fields for other intents are ignored. It does not describe return shapes or potential side effects in detail, so it earns a 4 rather than a 5.

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 uses a compact table to cover eight distinct intents, followed by targeted usage guidance and one example. Given 21 parameters and a tagged-union schema, the length is justified and structurally efficient.

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?

It covers routing behavior, required versus optional fields per intent, tslot sourcing, error behavior, and an example, which is substantial for a complex planner. Without an output schema, it names the answer type per intent but does not fully specify the return envelope for each intent, so it is complete 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 description coverage is 86%, so the schema already carries substantial parameter semantics. The description adds a valuable intent-to-fields table mapping which fields are required or optional for each `type`, plus an example and a note on tslot semantics. Some per-field details are repeated from the schema, keeping this at 4.

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 mechanism: a single typed object where `type` selects the intent and the tool returns an answer rather than a list of primitive calls. It also explicitly distinguishes this router from siblings such as emem_recall, emem_recall_polygon, 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?

The 'When to use' section gives explicit conditions for choosing this tool over the primitives and names the relevant alternatives. It also clarifies edge cases like tslot windows and unknown/missing `type` behavior.

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 establish read-only, open-world, idempotent, non-destructive behavior, and the description adds useful operational details: aliases are accepted, coordinates take precedence over text, and unrecognized arguments are surfaced. These details go beyond what the annotations declare and help the agent invoke the tool correctly.

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 follows with usage guidance, alternatives, parameter behavior, and an example. It is somewhat dense and includes internal-return detail, but most sentences earn their 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 the rich annotations, complete input schema, and existing output schema, the description supplies enough context: purpose, when to use it, alternatives, parameter precedence, and response inventory. Nothing critical is missing for correct selection or invocation.

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 that lat/lng must be numbers and that coordinates win when both coordinate and text inputs are provided. It repeats some alias information already present in the schema, so it is not fully additive.

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: get the canonical cell64 address of a real-world place, plus its band inventory. It also distinguishes this from emem_entity for object identities, so an agent can tell which lookup is appropriate.

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 says when to call this tool, names emem_entity as the alternative for object identities, and points to emem_inferences for nearby vouch research. It also routes packaged multi-part answers to emem_ask, giving clear sibling boundaries.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false; the description's note that each triple goes through recall and 'materializes on a miss' usefully explains the non-read-only side effect. It also discloses the 256-triple cap and that partial resolution is surfaced via `members`/`resolved`, going beyond the annotations, though it does not spell out permission or authorization requirements.

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?

Purpose and handle format are front-loaded, followed by when-to-use, limits, and an example — a sensible order. It is dense with domain jargon (cell/band/tslot, bundle_cid preimage, memory algebra), which costs a little readability, but no sentence is pure 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 no output schema, the description covers the return shape ('members' and 'resolved' for partially resolved bundles), the bundle_token format, the 256 cap with a note on round-trip planning, and the offline verification path. For a nested-object, multi-mode tool this is complete enough that an agent can invoke and interpret 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 baseline is 3, but the description adds real meaning: it distinguishes that a triple 'is resolved through recall and can bind a newer fact than the one you showed' while a cid 'binds that fact and no other' (triples vs fact_cids), and supplies worked example arguments. The mutually exclusive triples/fact_cids contract is reinforced rather than merely 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 first sentence gives a specific verb and resource ('Combine N (cell, band, tslot?) triples into ONE signed envelope'), and the later text explicitly differentiates from the sibling emem_memory_token ('Use this instead of N calls to emem_memory_token when the citation is one thing'). An agent can select this tool over its siblings without opening any 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 states the trigger condition ('when you must cite several (place, band, date) facts as one handle'), names the alternative it replaces, and gives a concrete example ('the EUDR baseline for these 8 plots at 2020-12-31'). It also points to /v1/verify_receipt for follow-up verification, so the decision path is complete.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond that: it warns not to pick a value and hide conflict, cautions to read the SCOPE before quoting a zero, explains the default only counts distinct attesters, and defines what qualifies as disagreement versus a mere refresh. This is exactly the extra behavioral context the annotations cannot carry.

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 purpose, then usage, then mechanics, then alternatives and an example — a sensible ordering for an 8-parameter tool. It is dense and slightly redundant, restating the band-kind severity formula that also appears in the min_severity schema description, but no sentence is truly 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?

With no output schema, the description still describes the return shape (severity 0-1, a citation per disputed fact, disagreement_scope on each record, every disputed cid cited in the receipt). Combined with full schema coverage and clear defaults, an agent has everything needed to invoke and interpret the result.

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 per-band-kind severity formula, the role of cell_prefix/band for narrowing, and the semantics of include_same_attester_sources including the derivation.fn_key and sources[].scheme conditions. The example arguments further clarify how the filters compose.

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 where the corpus disagrees with itself — and immediately defines what 'disagreement' means (two or more independent sources signing different values for the same place, band and time). It also distinguishes itself from siblings by naming emem_diff and emem_edges_recall as different operations, so an agent can tell it apart without opening another 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?

Gives an explicit when-to-use trigger ('do the sources agree on X', 'audit this claim') and routes to alternatives for adjacent needs ('To measure a pair, use emem_diff', 'To read the disagrees_with edge, use emem_edges_recall'). It also states the precise condition for the non-default mode: on a single-responder node, add include_same_attester_sources: true.

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 cover readOnly/idempotent/non-destructive. Description adds valuable context: byte-for-byte resolution, validation of non-empty parts and no `:` separator, and context-cost tradeoffs. Doesn't fully detail the band/observed_on provenance behavior but schema covers much of it.

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?

Format and example are well front-loaded, but the token-cost math (83-84 chars, 51 LLM tokens, 9.5x context) is lengthy and arguably belongs in the sibling bundle's description or docs; it dilutes the core call 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?

Output schema and full param schema carry the detail burden; description gives enough context to call correctly. Minor gap: doesn't explain when to supply the optional band/observed_on together versus alone.

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 four parameters in detail (band, observed_on, cell pattern, fact_cid format). Description adds the `:` separator constraint but little else beyond the schema; baseline 3 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?

States a specific verb (Make a citation handle) and gives the exact token format `emem:fact:<cell64>:<fact_cid>`. Clearly distinguishes itself from emem_echo_verify and emem_memory_bundle by naming both.

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, names emem_echo_verify before publishing, and routes multi-fact cases to emem_memory_bundle with concrete token-cost reasoning for when each applies.

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 readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds real behavioral context beyond that: null value/unit means an absence rather than a missing field, and a cid not held by this responder yields a typed 404 with a fallback path. It omits auth/permission and rate-limit behavior, so not a full 5.

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?

Purpose and output contract are front-loaded, then usage, then edge cases, then an example — a sensible order with a labeled 'When to use'. It is somewhat long for a one-parameter tool, with mild redundancy between the opening output description and the later null-semantics note, but nearly every sentence carries information.

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 an output schema and full annotations exist, the description still supplies everything an agent needs: what the token is, the trigger for calling it, the shape of the answer, null semantics, and failure handling with a next step. Nothing material 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?

Schema coverage is 100% for the single `token` parameter, so the schema already documents it and the baseline is 3. The description reinforces the token's format and supplies a concrete example argument, but adds little semantic meaning beyond what the schema states.

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 opening sentence states a specific verb (read/dereference) and a precise resource (an `emem:fact:<cell64>:<fact_cid>` citation handle) and states the return contract. It is clearly distinguishable from siblings like `emem_memory_token` (minting) and `emem_recall`, and the domain reference to memory algebra anchors it.

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' clause gives a concrete trigger: you have a memory_token from another agent or earlier turn and need the value. It also names fallback alternatives for the 404 case (/v1/fetch, mirror resolution). It does not explicitly contrast with sibling tools such as emem_memory_token or emem_recall, so it stops short of a full routing guide.

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 readOnlyHint=false, idempotentHint=true, openWorldHint=true — and the description supplies the missing 'why': a miss triggers an upstream fetch that is signed and stored, explaining both the write behavior and the first-call latency, while later calls hit cache. It also discloses that materialize_notes reports what was fetched and that empty notes mean no materializer. Remaining gap is modest: it doesn't spell out auth/permission requirements for materialization or failure modes on unfetchable bands.

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?

Purpose is front-loaded in sentence one, followed by a labeled 'When to use:' section and a concrete example call, which is strong structure. It is long and dense, with the fact_cid digression ('A fact_cid is NOT a fingerprint of the observation...') sitting between purpose and usage, but that length is largely justified by a 14-parameter, bi-temporal tools surface.

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 needn't explain return values, and it correctly focuses on selection semantics: cell vs. aliases, scope filtering behavior, materialization-on-miss, and the provenance/deterministic interaction. For a 14-parameter tool with nested scope and bi-temporal bounds, the description gives the agent enough to choose inputs and anticipate side effects in a single call.

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 carries the parameter burden and the baseline is 3. The description does add cross-parameter meaning the schema states only in fragments — that deterministic is sugar over provenance (direct_sensor + deterministic_index), that the two compose as an intersection, and that a fact_cid is responder-key-bound rather than a fingerprint of the observation — but it does not walk the parameter set or clarify the cell/lat/lng/place/cell64 alias precedence beyond what the schema already says.

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 gives a precise verb+resource: 'Read the signed facts at a canonical address (cell64)', and immediately pins the semantics as 'ensure(cell, bands), not get'. It distinguishes itself from siblings by name — emem_locate as the upstream step and emem_entity for cross-responder identity — so an agent can tell it apart without opening either 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?

It has an explicit 'When to use:' block ('Call this after emem_locate, or with a cell64 or a place name'), and it routes the agent away when the intent is different ('For identity across responders, use emem_entity'). It also explains the miss path (materializer fetches, signs, stores, returns in the same call) so the agent knows to expect the slow first call rather than retrying.

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 readOnly/idempotent/non-destructive, yet the description adds substantial non-obvious behavior: hosts strip `_meta` so 18 tools is a curated subset of 116, `name` short-circuits all other args, unlisted tools are still callable via tools/call, and unknown names return `did_you_mean` rather than an error. Only the exact response shape is left implicit.

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 what the tool is, then the loop, then triggers, then the when-to-use block. Efficient overall, though the caps-locked 18-vs-116 warning and the 'Example arguments' line are somewhat repetitive with the later prose.

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, and the description compensates well — it explains that results are grouped by question with one-line triggers and that `name` yields a full descriptor with schema, runnable example and annotations. A short note on the catalog body's pagination/size would close the last 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% and the schema descriptions already explain `q` substring semantics, `name` short-circuiting, `shape`, `bundle` and the category safety caveat in detail. The description adds a couple of usage examples (`q:ndvi`) and the AND-combination hint, but largely restates the schema, so baseline 3 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?

States a specific verb and resource: 'The map of emem's tools, and the one tool that finds all the others,' then explains it returns the working loop in order and groups every tool by the question it answers. An agent can tell this apart from emem_ask and emem_recall from the text alone.

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: Call this FIRST when you do not know which tool answers the question,' plus a second trigger (your list lacks a capability) and named alternatives (`emem_ask` answers in one call without primitive choice; `/mcp/full` registers the full catalog).

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/openWorldHint, yet the description adds substantial behavior: byte-for-byte verification, false forgery rather than a 400 for omissions, bad signatures returning 200 with valid:false (never 4xx), version-2 binding of the inclusion proof, and advisory-only epoch mismatch. This is rich context well 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?

It is front-loaded with purpose and critical warnings, and every warning about omissions earns its place. It is somewhat long and slightly repetitive (byte-for-byte stated twice) and the closing paragraph about the oversized example meanders, so not 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?

For a complex, nested, multi-param tool with no output schema, the description enumerates the return object fields and semantics ({valid, reason, failure_detail, signature_valid, merkle_proof_valid, ...}), explains failure reasons and edge cases, and covers input shape pitfalls. Nothing critical to correct invocation appears 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 schema already documents all four parameters, setting a 3 baseline. The description nonetheless adds meaning: signature/key may be byte arrays or the b32 fields and 'accepts no other names', dropping merkle_proof/preimage_version causes false forgery, and pubkey_b32 pins a signer — real value on top of 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?

States a specific verb and resource — 'Verify a signed receipt on the server' — and the title reinforces it with 'ed25519 receipt verifier'. It distinguishes itself from siblings by naming the browser /verify page, emem_memory_token_resolve, and third-party audit scenarios, so an agent can route 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?

Provides an explicit 'When to use' section: when the browser /verify page is unavailable and to audit a third-party receipt. It names the alternative path (resolve an emem:fact: token via emem_memory_token_resolve first, then pass the resulting receipt), covering both when to use and what to do instead.

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 annotations are non-obvious (readOnlyHint false on a tool called 'fetch'), and the description explains exactly why: a cell handle MATERIALIZES a missing band, fetching/signing/storing it, while a fact handle writes nothing. It also discloses value fidelity ('exact decimal string that the responder signed, never a new format') and the large-body fallback (returns a URL). This adds substantial context beyond the annotations rather than restating 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 lead sentence front-loads what the tool returns, and the usage block is clearly demarcated. It is dense and jargon-heavy with a slightly redundant restatement ('A fact handle writes nothing'), but nearly every sentence carries routing or behavioral information.

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?

An output schema exists, yet the description still orients the agent on the shape of the result (reading, body, URL, metadata) and on the fallback path when the body is too large. Combined with the flag rationale, nothing needed 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 baseline is 3, but the description goes further by attaching distinct semantics to each id form: fact citations are read-only, cell handles trigger materialization. That behavioral split is not in the schema and directly affects how an agent should choose the id to pass.

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 ('Dereference an id from `search`') and immediately enumerates what comes back: the one-line reading, signed body, serving URL, and metadata. It distinguishes itself from siblings `search`, `emem_recall`, and `emem_echo_verify` by name and role, so an agent can route without opening another 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?

'When to use: Call this on each result that you will cite, before you quote the number' gives an explicit trigger and ordering constraint, and it names the downstream tool (`emem_echo_verify` grades what you emit). It also contrasts behavior with `emem_recall` for cell handles, giving the agent a comparison point for the nearest sibling.

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 (readOnlyHint false, openWorldHint true, idempotentHint true, destructiveHint false) are explicitly reconciled — the description explains that a cold cell causes materialization (fetch, sign, store), which is why readOnlyHint is false. It also discloses the wire cap and that index 0 carries the TRUE total. The remaining gap is that band/cell jargon is undefined and no rate or cost behavior is mentioned.

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-loads purpose, then result shape, then query semantics, then when-to-use and an example — a sound order with little waste. A few phrasings are cryptic ('cap for the wire', 'cell64', 'band') and cost it the top score.

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?

An output schema exists, so explaining return values is optional, yet the description still sketches the entry structure and the index-0 convention. Combined with an explicit when-to-use, the alternative, and the materialization caveat, an agent has everything needed 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 baseline is 3, but the description goes beyond it: a topic word narrows results without ever emptying them, and a cell64/handle/citation input resolves to the single cited fact. That adds behavioral meaning the schema's enumeration does not convey.

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 — searching emem's signed corpus and returning each signed fact as a citable source — and immediately describes the result shape (id, title with band/place/signed value, stable url). It is clearly differentiated from siblings by naming fetch as the expander and emem_ask as the combined-answer alternative.

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' block says to call this first when the question is about a place and the answer must have citations, and names the alternative (emem_ask) with the condition that selects it. It even notes the input can be a citation handle, which returns exactly one fact.

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