Magnemo

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

Annotations already mark it read-only, idempotent, and non-destructive, so the bar is lower. The description goes further by disclosing the deterministic output property ('same vault state, same bytes'), the strict ordering requirement, and the anti-fabrication rule ('Charter first, verbatim, never fabricated'). This adds meaningful behavioral context beyond the structured 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 two dense sentences with no filler. It front-loads the core object and rule, lists contents in a natural reading order, and closes with a deterministic guarantee. 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 read-only boot tool with no required parameters and no output schema, this is complete. It tells the agent what will be read, in what order, when to call it, and what property to expect. Nothing essential 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 both parameters (class and scope) having enums and descriptions. The tool description adds no parameter-specific details, but it doesn't need to because the schema fully documents them. Baseline 3 is appropriate.

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

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

The description clearly identifies the resource ('boot pack'), specifies the action (read it FIRST), and enumerates the exact ordered contents. It also adds the deterministic property ('same vault state, same bytes'), which makes the tool's purpose unambiguous and distinct from generic retrieval.

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

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

It explicitly prescribes when to use the tool: 'Read it FIRST on every wake.' This is clear contextual guidance. It doesn't explicitly contrast with siblings like retrieve or handoff, but the every-wake-first instruction is strong enough that an agent can infer this is the mandatory entry point.

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, destructiveHint=false, so the safety profile is covered; the description adds the real state outcome — the note is marked rejected with the reason attached and permanently excluded from Memory. It does not say whether a drop can be undone or what happens if the gate condition is violated.

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?

Two tight sentences, with the gating condition front-loaded ahead of the effect. Every clause carries information an agent needs.

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 two-parameter mutation with full schema coverage and annotations, the description supplies the precondition and the resulting state, which is what an agent needs to call it correctly. No output schema exists, so the only minor gap is error/reversal behavior.

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 both parameters are already documented, including the id-or-last-8-characters convention and that reason should be the person's own words. The description only echoes 'with their reason', adding no format or fallback guidance 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 and resource: it sets a staged note aside as rejected, recording the reason, and the note never becomes Memory. That is enough for an agent to tell it apart from siblings like keep or stage without opening a schema, though it never names those siblings directly.

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 a sharp, explicit precondition — call it only when the person has rejected the note in their own words in this conversation — which also implies the negative case (don't drop on your own inference). It stops short of naming keep or stage as the alternative when that condition isn't met.

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=false and destructiveHint=false; the description corroborates the non-idempotent append model ('appends telemetry ... to the append-only handoffs ledger') and clarifies that nothing is destroyed ('later or no answer leaves them staged and blocks nothing'). It also discloses the staging side effect and the keep/pick/later prompt, which annotations cannot convey. It stops short of stating permissions or error behavior.

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 core purpose and its two side effects are front-loaded in the first sentence, and the downstream inheritance follows immediately. The trailing 'A pause:' sentence is dense and awkwardly phrased ('where the client can draw a question'), costing some 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?

For a non-idempotent mutation with no output schema, the description covers what is written, where it goes, the staging side effect, and what the next bootpack does with it. Safety is covered by annotations. The only gap is that the pause/prompt flow is described in terms an agent may find hard to act on, but nothing needed 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 67%; the one undocumented field (`trigger`) is only an enum. The description maps all three parameters in the parenthetical 'usage %, trigger, what was cut' and gives semantic meaning to the `wall` trigger via the doctrine ('do not ride to the wall'). It adds modest value over the schema but does not fully explain when to choose 'compaction' vs 'other'.

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: records a session boundary by appending telemetry to an append-only ledger AND staging a handoff note. An agent can tell this is the boundary-recording tool rather than a plain staging tool. It does not explicitly distinguish itself from the sibling `stage`, which also stages notes, leaving some ambiguity about overlap.

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 doctrine line ('hand off at ~88-90%, do not ride to the wall') gives a concrete condition for calling it, and 'The next bootpack inherits it' explains the downstream purpose. However, it never names an alternative or an exclusion ('use X instead when...'), so the when-not case is absent.

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

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

Annotations only declare the write/idempotent/safe profile; the description adds substantial behavior beyond them: the resulting Memory record is tagged 'unverified' consent, the Sentinel-held case is excluded, 'all' expands to every pending note as separate ledger lines, and a hard cap of 50 keeps per local day resetting at the vault machine's midnight with two documented ways around 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?

The gating condition is front-loaded in the first clause and every sentence carries information (consent rule, result state, exclusion, all-branch, cap, workarounds). It is dense and slightly run-on in places ('A note Sentinel is holding is not kept this way'), which costs a point but no filler is present.

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 and a single documented parameter, the description covers the consent gate, the resulting side effects, the batch case, the rate limit, and the escape hatches — enough to invoke correctly. It stops short of saying what the call returns or what a failed cap does to the note's pending state.

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 already documents id / last-8 / "all", so the baseline applies. The description still adds meaning the schema lacks: what the "all" branch actually does ('keeps every note pending lists, when the person said keep all; each is its own ledger line') and that cap counting applies per note.

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 — keep a staged note that the person consented to — and immediately names the resulting state ('The note becomes Memory'). It also carves out cases handled elsewhere ('A note Sentinel is holding is not kept this way'), so an agent can distinguish it from stage/drop/handoff 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?

Gives an explicit precondition ('only when the person has said yes to this note in their own words in this conversation'), an explicit prohibition ('never keep on your own judgment', 'never draw a panel'), and names the alternative escalation paths ('magnemo yes <id>' or the client's one-question handoff). When-to-use, when-not-to-use, and alternatives are all present.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so the bar is low; the description still adds real behavior – that the call is non-blocking, that unanswered notes are not lost, and that a Sentinel-held note returns only its alert rather than its body. That last caveat is a genuine edge case an agent could otherwise get wrong.

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 there is little outright filler, but the metaphorical register ('the one line to say about them', 'the person's keep') costs tokens without adding precision. Two of the three sentences do real work; the framing sentence does not.

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 single-param, read-only, no-output-schema tool, the definition covers return shape (note body, provenance, the 'staged · not yet Memory' label) and the Sentinel exception, which is what an agent needs to call and interpret it. Only the sibling boundary is absent.

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 already defines the id/last-8-characters format, so the baseline is 3. The description goes further by explaining what supplying the id actually yields – the full body plus provenance – which is semantic meaning the schema 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?

The core is decipherable – it lists staged notes that nobody has answered yet – but it is wrapped in in-group metaphor ('the person's keep', 'Sentinel', 'staged · not yet Memory') that an agent unfamiliar with this vocabulary must reverse-engineer. It does not name any of the siblings (retrieve, keep, stage) to draw the boundary, so differentiation is inferred rather than stated.

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?

Timing is unusually explicit: 'at a pause, at the end of your own turn, never mid-work', plus the reassurance that 'later, or no answer, is fine: nothing blocks and nothing is lost.' What's missing is routing against alternatives such as retrieve, but the when-to-call guidance itself is concrete.

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, openWorldHint=false, idempotentHint=true, and destructiveHint=false Score. The description goes beyond annotations by disclosing that the payload is budgeted and truncated/downgraded to fit, that scope is partition-walled, that payload size is logged to Foresight counters, and that results are never raw dumps. This materially enriches the agent's understanding of side effects and constraints.

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 two dense sentences that front-load the core purpose and then add essential behavioral details. Every clause adds value, and there is no filler or 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?

Given the absence of an output schema, the description reasonably explains the return shape: mn:// pointers plus snippet renditions, never raw dumps. It also covers budget truncation, scope constraints, and logging. It stops short of explaining edge cases like empty results or what rid means, but for a retrieval tool with rich annotations and schema, it is largely 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 75%, so the schema documents most parameters. The description adds meaning by explaining that budget controls payload truncation/downgrade and that scope is partition-walled. It also clarifies that results are scored and budgeted, which relates to the budget parameter. The k parameter is not explicitly addressed, but the schema provides range and default context.

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: retrieve canonical, keyholder-approved memory relevant to a query. It also distinguishes the tool's behavior from a general memory lookup by specifying scored, budgeted payloads with mn:// pointers and snippet renditions. This clearly separates it from the unrelated sibling tools.

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

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

The description gives clear context for when to use this tool: when canonical memory relevant to a query is needed segments. It also provides a usage instruction ('Cite the returned rid when the action resolves'). However, it does not explicitly state when not to use it or name alternatives, missing the top tier of 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?

Goes well past the annotations: declares it is 'the only write verb', that notes land in _staging/ with mandatory provenance, that malformed or paperless notes are refused, and that the call is non-blocking and returns the staged id, salience, a duplicate flag and a scripted line. With no output schema, this return-value disclosure is especially 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 opening 'Remembering means proposing' is a philosophical preamble that delays the operational content, and the middle sentence about contact details and labels is cryptic. The substantive material (staging location, refusal rules, return values, non-blocking behaviour) is present but scattered rather than front-loaded.

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 2-parameter nested write tool with no output schema and no annotations beyond safety hints, the description covers lifecycle placement, refusal conditions, non-blocking semantics and return contents. The main gap is guidance on the nested note fields (partition/store/impact/supersedes) that the schema leaves undescribed.

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 reported at 0%, so the description has to carry the load, and it only partially does: 'mandatory provenance' explains the provenance object's role and the 'paperless' refusal clarifies source is required, plus a hint about labelling untrusted content (taint). It says nothing about note.partition, note.store, note.impact, note.supersedes or how tags are used.

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 ('Stage a memory candidate for the person's review') and pins down the scope: it writes only into _staging/ and 'never touches canon'. It implicitly distinguishes itself from siblings by naming keep as the act that makes the note Memory, so an agent can tell staging apart from promotion.

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 clear operating context: 'It never waits and asks nothing: keep working', and 'Ask about what you staged only at a pause (see pending), never mid-work' routes follow-up questions to the pending sibling. It doesn't spell out when staging is inappropriate versus just using retrieve, but the alternative paths are named.

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