emem

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

Despite annotations already covering readOnlyHint/destructiveHint/idempotentHint, the description adds substantial behavioral context beyond those: the server-side resolve/classify/recall chain with auto-materializing bands, the signed receipt structure at the envelope root, the caveats block surfacing grid resolution and revisit cadence, and the default slim response size (~5 KB) under MCP's 25 KB cap. It also discloses that `verbose` expands the response, and that the deterministic answer never calls a model.

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

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

The description is long and information-dense, but every sentence serves a purpose: usage, parameter interplay, return structure, edge cases, and version-flavored behavior. It is front-loaded with the core purpose, though the middle section is dense and could be organized more tightly. For a tool with 11 parameters and a complex envelope, the length is justified over conciseness.

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

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

Given the tool's complexity — 11 parameters, a rich multi-band response envelope, fabricated facts, signed receipts, aliases, and output-size control — the description is remarkably complete. It covers parameter resolution order, opt-in heavy sections, output shape, error behaviors (unroutable model, out-of-scope question), and performance caveats (image adds 1-2 s, Cosmos 13-22 s). No output schema exists, so the description rightly carries the burden of return-value disclosure.

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 meaningful semantics beyond the schema: how `place` is geocoded (OSM Nominatim), the mutual exclusivity of location parameters (`cell`, `place`, `lat`+`lng`), the behavior and risks of `model` (including refusal rather than silent substitution), and the distinction between `answer` and `model_answer`. It doesn't fully explain every enum value in `include`, but that's the schema's job.

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

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

The description opens with a specific verb+resource ('Single-shot free-text answer about a real-world location') and differentiates the tool from a manual primitive composition by describing the server-side locate → recall → algorithm chain. It clearly distinguishes it from siblings like emem_locate, emem_recall, and emem_entity by stating it returns a packaged, citation-bearing answer envelope for a specific location plus question.

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

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

The description explicitly states when to use it ('Use when the question concerns a specific real-world place and a packaged, citation-bearing answer is preferable to manual primitive composition') and explains how to forward parameters ('Forward the user's question verbatim as `q` plus the location as `place`...'). It also addresses out-of-scope behavior with `topic_routing.matched_topic: null`, giving the agent clear routing guidance.

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

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

Beyond the annotations, the description discloses several non-obvious behaviors: bare cid produces degraded:true while skipping the cell-binding check, non-52-character cids are refused as damaged, strict changes exactly one outcome, and JSON numbers lose trailing digits before comparison. This is substantial behavioral context that annotations alone 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?

The description is front-loaded with the core behavior, then moves into usage, edge cases, and an example. It is longer than strictly necessary because of motivational framing ('nothing else in the loop notices') and repeated schema guidance, but the organization keeps the extra length usable.

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 verification tool with an output schema and non-destructive/idempotent annotations, the description covers the essential call scenario, return semantics, failure modes, damaged-citation handling, exact-string requirement, and a concrete example. An agent has what it needs to invoke the tool 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?

The input schema already explains all three parameters with 100% coverage, so the baseline is met. The prose adds practical emphasis on sending claimed_value as an exact string and pairing it with value_verbatim, which reinforces the schema's warnings, though it largely echoes rather than substantially extends the schema.

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

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

The description opens with a specific verb and resource: 'Grade a value you are about to emit against the signed fact your citation points at,' and it states the main outcome (matches/drift). It does not explicitly contrast itself with sibling tools such as emem_verify_receipt, so it stops just short of full sibling differentiation.

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 immediately before publishing, logging, or handing on any value you took from an emem fact' is an explicit trigger, and it gives clear behavior guidance ('treat a false matches as a gate'). It names a companion operation (value_verbatim from resolve) but does not list when-not-to-use conditions or explicit alternatives, so it lacks the full exclusion guidance for 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 (idempotentHint=true, readOnlyHint=false) are complemented by description details: the same entity_cid is minted for the same object, external IDs dominate identity resolution, and a signed receipt is returned. This adds meaningful behavioral context beyond the annotations without any contradiction.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description discloses far more than annotations alone: mode tradeoffs (~1000× faster, ~65% recall@10), the open-world empty-result meaning ("empty result means nobody has attested a vector nearby"), and the ANN fast-path bypass for scope/as_of with the honest-cost tradeoff ("brute-force scan instead... the call is slower"). Filter semantics ("DROPPED rather than treated as false") and bi-temporal candidate-dropping are also candidly stated. No contradiction with annotations; there is only a soft tension between readOnlyHint=false and "materialises nothing", but the receipt is returned to the caller rather than persisted.

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 mechanism and return shape, then a labeled "When to use" block, then an example. It is on the longer side and the mode paragraph partly duplicates the schema's mode description, but every sentence carries either selection or invocation information rather than filler.

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

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

For a 10-parameter tool with nested objects and no output schema, the description covers the entire invocation surface: return contract (neighbours with cell64/score/band plus signed receipt), empty-result semantics, k bounds, key forms, band choices, mode tradeoffs, and the scope/filter/as_of behaviors. An agent can select and invoke this tool correctly from the text 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% and the schema's own parameter descriptions are already rich (mode byte-costs, filter drop rule, scope bypass). The description still adds non-redundant value: key formats (cell64 vs inline:[x,y,...]), band dimensionality (128-D foundation vs 1152-D 9-vintage 2017–2025 fusion) with the exact band name to pass, and a concrete example. That lifts it above the baseline-3 for fully covered schemas.

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 line names a specific operation – k-NN over the corpus – with explicit input forms ("by cell embedding or inline vector") and a concrete return contract ("neighbours ordered nearest-first, each with cell64, score and the band scanned"). The trigger phrases "find places like X" / "where else looks like this" clearly separate it from siblings like emem_recall and emem_locate. It adds method and output detail well beyond the title.

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 with concrete user-phrasing triggers and the embedding-input case, plus a worked example argument {"key":"damO.zb000.xUti.zde78","k":10}. What is missing is explicit when-not-to-use guidance or named sibling alternatives, so exclusion routing is left 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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds substantial behavioral context: the ADVISORY that nothing is blocked, that a citation this responder does not hold is never a denial, and critically that 'a check that read nothing still answers allow.' It also discloses exact deny codes and fix semantics. This is exactly the kind of subtle behavior an agent must know before relying on the result.

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

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

The description is long but information-dense, and every section earns its place: output format, codes, advisory, when-to-use, shape caveats, enforcement alternative, example. The core purpose and machine-readable output are front-loaded before the caveats. It loses one point only because a few asides (the memory-algebra link, the selfhost integration list) are tangential for a single invocation decision.

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

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

For a tool with 5 parameters, an output schema, and subtle behavioral traps, the description is remarkably complete. It covers the exact output string format, all deny codes and fixes, the advisory open-world behavior, empty-read behavior, cross-framework payload handling, the enforcement alternative, and a worked example. An agent has everything needed to call this 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. The description earns a 4 by adding practical semantics beyond the schema: a concrete example argument, the rationale for claim_gating ('reports on the absence of a citation rather than on a failed check'), and the practical consequence of shape selection ('a CloudEvent whose citation sits at data.text is invisible to the native reader'). It also clarifies that shape only affects reading, not the output envelope.

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: 'Run emem-guard's policy pipeline over text you are about to send, against this responder's corpus,' then specifies exactly what happens (finds every emem: citation, resolves each one, returns allow or deny). It differentiates from siblings by framing this as the consult-inline tool versus emem_guard_selfhost for enforcement, and by the draft-checking scenario, which none of the sibling names suggest.

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' guidance names concrete triggers: call on your own draft before asserting something, or on a tool result before reasoning on it. It also gives explicit when-not-to-use guidance: 'To ENFORCE this rather than consult it, run your own node: emem_guard_selfhost returns the procedure.' The shape parameter guidance further clarifies when to set non-native shapes versus sending native texts/messages.

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a compact table mapping each intent to required/optional fields and answer shape, clarifies that fields for other intents are ignored (tagged union), and gives a concrete example. It also explains tslot semantics (band-tempo-relative, from emem_trajectory) beyond the schema.

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

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

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

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

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

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

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the description's added value is context beyond that. It discloses two non-obvious behaviors: a typo in an undeclared key is reported in `_unrecognised_arguments` rather than erroring, and coordinates win when both coordinates and a place name arrive. It also explains the response's three sub-fields, which is useful given no output schema.

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

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

The description is longer than average but well-structured: purpose first, then input rules, then when-to-use and response details, then an example. Every section carries necessary content for a spatial-resolution tool with six parameters and no output schema. A minor wordiness, such as the metaphorical 'so two models refer to the same ground instead of two descriptions of it,' is acceptable and aids clarity.

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

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

With no output schema, the description takes on the burden of explaining return shape, which it does by naming `data_at_this_cell` and its three sub-fields. It also covers input alternatives, aliases, precedence, error-friendly behavior, and explicit routes to sibling tools. An agent has everything needed to call this tool 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 value by summarizing that `q`, `query`, and `name` are all accepted spellings of `place`, and that coordinates win when both are supplied. This is a concise cross-field semantic that is not immediately obvious from the individual property descriptions.

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

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

The description names a specific verb and resource: it 'mints the canonical, vendor-neutral address (cell64) for a real-world place' and also returns a topic-grouped inventory of bands and algorithms. It clearly distinguishes itself from emem_entity (object identity) and emem_ask (single-shot full chain).

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

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

Explicitly states when to use: 'whenever the input refers to a real-world location and the next step needs the cell64 identifier or wants to know which bands are available before recalling.' It names alternatives and when to choose them: use emem_entity for first-class object identity and emem_ask for the single-shot packaged answer. It also clarifies coordinate vs. text input precedence.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description discloses materialization on miss, slower first-call behavior, materialize_notes in response, empty-result semantics, responder-bound CIDs, and receipt-relevant filtering. This goes well beyond the annotations (readOnlyHint: false, openWorldHint: true, idempotentHint: true) and gives the agent an accurate model of side effects and response behavior. No contradiction with annotations; the false readOnlyHint is consistent with the described auto-materialization.

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

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

The description is long, but the tool is genuinely complex with 14 parameters and rich behavioral caveats. The content is front-loaded with the core read/materialization behavior, then organized into use guidance, important caveats, and an example. Each section earns its place and avoids empty 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?

Given the tool's complexity, the presence of an output schema, and full schema coverage, the description is remarkably complete. It covers the calling sequence, materialization behavior, response notes, identity semantics, deterministic/provenance selection, temporal bounds, scope filtering, and the meaning of empty results. An agent has enough context to invoke this tool correctly in a wide range of scenarios.

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

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

Although schema coverage is 100%, the description adds meaningful semantic context beyond the schema: the distinction between deterministic and provenance filters, how band and bands merge, the meaning of scope filtering for tenant isolation, the behavior of include freshness/edges/provenance, and the bi-temporal meanings of as_of_tslot and as_of_signed_at. This is substantial added value beyond parameter names and brief schema descriptions.

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

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

The description states a specific action ('Read the signed facts at a canonical address (cell64)') and immediately clarifies the auto-materialization behavior on a miss. It also distinguishes the tool from emem_entity by explaining that fact_cids are responder-specific and do not cross identity boundaries, giving an agent a clear basis for selecting this tool.

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

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

The description explicitly says 'Call after emem_locate (or with a known cell64)' and names the alternative tool emem_entity for identity that crosses responders. It also explains when to use deterministic/provenance filtering and that any wired band can be recalled without seeding, giving clear selection and sequencing guidance.

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

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

Annotations already mark readOnlyHint/idempotentHint true, and the description adds substantial non-obvious behavior on top: the tool advertises only a small core loop by default so absence from a tool list does not mean absence from the server, and the ALL-CAPS warning explains that hosts strip _meta/_discovery fields so the 108 count is deliberately repeated in the description. It also discloses that catalogued tools stay callable by name through tools/call at either endpoint.

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 and the When-to-use section is clearly delineated with an example, but the middle is verbose: the capslock sentence packs a real operational fact into a long, winding justification, and two sentences about catalogued tools being callable via tools/call partly repeat each other.

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 six-parameter discovery tool with no output schema, the description covers return shape (working-loop order, question-grouped tools, one-line triggers, full descriptor for name), the critical 108-vs-16 context trap, the tools/call mechanism, and routing to alternatives. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% with each of the six parameters already richly documented (substring match semantics, name short-circuit, did_you_mean, category-not-safety warning). The description adds only light usage pointers — pass q for topic, name for exact schema, no arguments for the whole map — plus an example, so it stays at the baseline rather than compensating for any schema gap.

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 by naming the exact job — 'The map of emem's tool surface' — and describes the concrete returns: the working loop in walk order, then tools grouped by question with one-line triggers. It distinguishes itself from siblings by naming what it is not: emem_ask for one-shot answers and the /mcp/full endpoint for a fully registered catalog.

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 saying to call this FIRST when you don't know which tool answers or need a capability not visible in the tool list. It also states exclusions and alternatives: reconnect to /mcp/full to register the full catalog, or use emem_ask for a one-shot answer without picking a primitive.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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