emem

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

Annotations only give safety hints (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false); the description goes well beyond them by disclosing the projection's shape, that `_projection` names what was removed, that a `routed_to` other than answer returns complete, and the model-routing refusal modes (ambiguous fragment, unroutable name, busy/down, Cosmos without GPU). It does not explain cost or why readOnlyHint is false for what reads as a query tool, so it is rich but not exhaustive.

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 and 'When to use', but then runs into a long unpunctuated enumeration of return fields ('It has `answer`, `receipt`, ... `spatial_trace` and `scene_url`') and a REST-vs-MCP differential ('POST /v1/ask has more: caveats, topic_routing, reasoning...') that is not actionable over MCP. Several sentences re-describe what the output schema already exposes rather than earning 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?

With an output schema present the description need not explain return values, and it still covers when to use it, the location-parameter alternatives, model behavior and routing. Minor gaps remain: the possible `routed_to` values and their meaning, and any latency/rate context beyond the 'adds ~1-2 s' note in the schema.

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 value by framing the mutually exclusive location inputs ('Send the question as `q`, with `place`, `cell` or `lat`+`lng`'), noting `model` yields an extra `model_answer` alongside the deterministic `answer`, and supplying a worked example of `q`+`place`.

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 with scope: 'Answer a free-text question about a real-world location in one call.' It also names the internal chain (locate/recall/algorithm) and explicitly distinguishes itself from emem_intent did_change / emem_diff for change-over-time questions, so an agent can separate it from siblings 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?

Opens with an explicit 'When to use: Call this when the question is about a specific place and the answer must carry its evidence,' including the location-input alternatives (`place`, `cell`, `lat`+`lng`). It also routes a named case away ('For how X changed, use emem_intent did_change or emem_diff'), giving both condition and alternative.

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

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

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?

Beyond the annotations, the description discloses several behavioral traits: an unknown/missing type returns a needs_intent_type envelope rather than a hard error, the plan executes in the same call (results, not a call list), `window` is tslots not dates and must be sourced from emem_trajectory, and `areas` caps at 6. It does not address the tension that annotations set readOnlyHint=false for what reads as a query/answer tool, nor does it describe latency or limits.

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 a compact table, then when-to-use, then an example. Given 21 parameters and 8 intents this density is justified, though a couple of parenthetical asides ('type:"ask" sends it there') and the repeated window/tslot warning add minor redundancy.

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 21-parameter tagged-union tool with nested objects and no output schema, the definition is complete: the table's 'answers' column conveys the return semantics per intent, the error envelope behavior is stated, cross-tool dependencies (emem_trajectory for tslots) are called out, and an example argument object is provided.

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 already 86%, so the schema carries most per-field meaning. The description still adds real value with the routing table mapping each `type` to its needs/optional fields, the instruction to send only the fields in the row, the note that `window` values are epoch-relative tslots (not unix/date strings), and a worked example. It stops short of documenting every field, so it complements rather than replaces 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 states a specific verb and resource ('State what you want in one typed object and get the answer'), then enumerates the eight intent rows with their required/optional fields and answers. It explicitly distinguishes itself from siblings (emem_recall, emem_recall_polygon, emem_ask), so an agent can route without opening other 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' block: use this when the question matches one of the eight rows and you prefer to state the goal, otherwise call the primitive. Concrete alternatives are named per case (a band at a cell -> emem_recall, a region -> emem_recall_polygon, free text -> emem_ask), plus the note that named tools can be invoked through tools/call.

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/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-structured behavior: deterministic resolution ('every agent resolves a place to the same cell64'), input precedence ('when both arrive, the coordinates win'), and that unrecognised keys surface in `_unrecognised_arguments` so typos are visible. It stops short of error/rate-limit behavior, so not 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?

Front-loaded with the core purpose and an efficient usage block, with a concrete example argument. Slightly verbose: the alias sentence ('q, query and name are other names for place') restates what the 100%-covered schema already documents, which is minor redundancy.

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 return values needn't be enumerated, yet the description still characterizes the answer (bands/recipes by topic). With 6 optional params all documented, annotations covering safety, and precedence plus alias behavior explained, 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 description coverage is 100%, so baseline is 3. The description adds a precedence rule absent from the schema (coordinates win over free text when both arrive) and consolidates the alias set, giving an agent information the schema fields do not encode.

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: 'Get the canonical address (cell64) of a real-world place', plus what else the answer contains (bands/algorithms by topic). It explicitly distinguishes itself from the sibling emem_entity ('For an OBJECT identity ... instead of a cell, use emem_entity'), so an agent can route 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?

A dedicated 'When to use' block names the trigger condition (next step needs a cell64 or the bands there) and names two alternatives with their selecting conditions: emem_entity for object identity, emem_ask for a single packaged answer. When-not and alternatives are both explicit.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds non-obvious behavior the annotations cannot express: the 18-of-115 curated subset, the warning that hosts strip _meta, that any catalogued tool is callable by name via tools/call at either endpoint, that /mcp/full registers the full catalog, and that an unknown `name` yields a did_you_mean body rather than an error.

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 and the 'call this first' trigger are front-loaded, and the all-caps subset warning is deliberately prominent. It is somewhat long and repeats the curated-subset/unlisted-tool point across two paragraphs, which costs a little, but every sentence carries routing 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?

With no output schema, the description still tells the agent what comes back: tools grouped by the question they answer with a one-line trigger each, an example that runs for `name`, and a did_you_mean fallback. For a zero-required-parameter discovery tool, nothing an agent needs before calling 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 descriptions are themselves unusually detailed (substring semantics, AND-combination, short-circuit on `name`, enum meanings), so the description's parameter notes largely restate structured data. It does add framing ('q searches by topic') and a concrete example argument, but this is the baseline case where the schema does the heavy lifting.

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

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

It states a specific role in one line: 'The map of emem's tools, and the one tool that finds all the others,' plus the working loop ordering. It also distinguishes itself from the nearest sibling by noting that 'emem_ask answers in one call without a choice of primitive,' so an agent can route between them 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?

Explicit when-to-use is given ('Call this FIRST when you do not know which tool answers the question') along with a second trigger ('when your list does not have a capability') and the named alternative (emem_ask). The unlisted-tool scenario is called out as a positive reason to call, which is exactly the routing decision an agent needs.

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.