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

With no annotations, the description carries the burden and largely meets it: it discloses that this is a read action returning a briefing identical to connect-time server instructions. It also gives the agent a clear mental model of the content, though it does not specify the exact return format or whether any auth is required.

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 sentences with no wasted words: the first front-loads what the tool reveals, the second explains when to use it. Every clause adds value.

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

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

For a zero-parameter informational tool with no output schema, the description is complete: it tells the agent what the briefing covers, that it repeats connect-time instructions, and when to invoke it. An agent can decide to call and know what to expect.

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

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

The tool has zero parameters and the schema is fully covered, so there is no parameter information for the description to add. Baseline 4 applies because nothing is missing for 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 uses a specific verb ('Read') and names a clear resource: Mnemosyne OS's identity and the operational rules an agent must honor. It enumerates the content areas (governance, vault protection, spine model, do/don't behavior), making it unambiguous and distinct from the operational 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?

It states exactly when to call: to re-read the briefing or when the client did not surface the server instructions. Since this is the only informational tool among the siblings, no alternative routing is required; the condition is explicit and actionable.

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

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

No annotations are present, and the description takes responsibility for disclosing important behavior: the write is routed through the widget's own store and is immediately what the human sees; the dev-install headless daemon behavior versus npm requiring the app running is stated. This goes beyond a simple 'creates'; only missing error/reversibility details.

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?

All 4 sentences are useful and information-dense, covering purpose, context, deployment behavior, and sibling alternatives. Slightly longer than strictly necessary but each clause earns its place, so only 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?

Given there is no output schema and no annotations, the description supplies the key operational context (widget store, dev vs npm daemon, sibling routes). It omits return/error shape, but the schema fully documents the input side and this is a frequent write tool; enough for correct selection and invocation.

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

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

The input schema has 100% description coverage for the lone array of events, already including formats and nuances like ISO 8601 and 'do not set Z unless UTC'. The description adds generic context ('appointments or deadlines') but no additional per-parameter meaning beyond the schema, hitting the baseline 3.

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

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

States a specific verb and resource: 'Put appointments or deadlines into the human's calendar (the Agenda widget on their canvas).' Distinguishes from siblings by explicitly naming mnemosyne_agenda_list, update, and remove for other operations, so there is no ambiguity with the todo tools or agenda_remove.

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 tells when to use: 'Use it when a conversation names a specific date/time to remember' and gives examples. It also points to the exact sibling tools for reading/updating/removing, covering when not to use this tool. No inference needed.

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?

With no annotations provided, the description carries full responsibility and does so thoroughly. It discloses that there is no archive, removal cannot be undone, repeating events are collapsed to one occurrence with cadence and next date, times are machine-local, and headless operation depends on dev install vs npm install. This goes far beyond basic read-vs-write labeling.

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

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

The description is dense but every sentence earns its place: purpose, ID requirement, mutation caveats, repeating-event behavior, timezone, environment constraint, and scope. The most important operational guidance is 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?

There is no output schema, so the description must convey what the caller gets back. It does: appointments with IDs, one entry for repeating events with cadence and next occurrence, and local times. Combined with full parameter coverage the tool is effectively self-contained for an agent to use 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 covers all 4 parameters with full descriptions, so the baseline is 3. The tool description does not add parameter-level detail, though it does clarify the semantics of repeating events, which helps interpret from/to and include_past results.

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: 'Read the human's calendar back' with a time-window scope. It also names the essential output (appointment IDs) and differentiates itself from the mutation siblings by explaining that update/remove require these IDs.

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 instructs to call this BEFORE mnemosyne_agenda_update or mnemosyne_agenda_remove, explains that those tools identify appointments by ID only, and warns about irreversible removal. It also gives environment-specific guidance for dev installs vs npm installs, leaving no ambiguity about when the tool works.

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?

With no annotations, the description carries the full burden of behavioral disclosure and does so thoroughly: removal is permanent with no archive, repeating appointments are removed as a whole series, and the tool names each removed appointment by title and start time in its response. The headless-daemon requirement is also disclosed, making side effects visible before invocation.

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

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

The description is dense but every sentence contributes a distinct operational fact. The core instruction to read first and pass ids is front-loaded, and the remaining caveats are ordered by practical importance with 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?

For a one-parameter destructive action with no output schema, the description covers the input source, matching rules, deletion permanence, recurrence behavior, runtime prerequisites, and what the response will report. Nothing critical is missing for an agent to invoke it safely.

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

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

The schema already documents the ids parameter well, but the description adds important semantic constraints: ids must come from mnemosyne_agenda_list, matching is strictly by id rather than by title or date, and there is a concrete warning against natural-language date matching. This adds real meaning beyond the schema's type and count.

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

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

The description states a clear, specific verb and resource: REMOVE appointments from the human's calendar. It also distinguishes this tool from alternatives by explicitly saying it never matches by title or date, which makes the purpose unmistakable even among agenda siblings.

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 tells the agent to read appointments with mnemosyne_agenda_list first and pass the returned ids, and warns against title- or date-based matching with a concrete failure example. It also addresses repeating appointments and the dev-install versus npm environment differences, which leaves no ambiguity about how and when to use it.

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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses partial-update behavior (omitted fields untouched, null clears), strict refusal of unreadable start/end times, refusal of unsupported cadences, environment-dependent execution (headless daemon vs app running), and the required scope: agenda:write.

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 front-loads the primary purpose and then packs prerequisites, error behavior, and environment notes into a compact paragraph. Every sentence adds operational value, with no filler or repetition.

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 tool with a nested changes array, no output schema, and no annotations, the description covers the essential decision points: how to identify the appointment, how omitted/null fields behave, what inputs are refused, and whether the daemon is required. The only minor gap is atomicity across the array, but that is not essential for correctly invoking the 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 already documents every field (100% coverage), so the baseline is 3. The description adds a global update rule 'a field you leave out is left alone; passing null CLEARS it' and instructs the agent to source event_id from mnemosyne_agenda_list, which goes beyond the schema by clarifying omission vs null semantics.

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 the verb 'CHANGE' and names the exact resource: an appointment already in the human's calendar. It enumerates the supported mutations (move, rename, add/drop reminders, start/stop repeating) and explicitly says appointments are identified by the id from mnemosyne_agenda_list, making it clearly distinct from add/remove/list siblings.

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

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

The description gives an explicit prerequisite: call mnemosyne_agenda_list first to obtain the appointment id. It also provides operational context such as null-clears-field semantics and the daemon/running-app requirement on dev installs vs npm installs, but it never explicitly names when-not alternatives like agenda_add or agenda_remove.

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?

With no annotations provided, the description carries the full burden and does it well. It discloses that answers come from transcript files on disk, that Mnemosyne OS and a token are not required, and that each recorded directory is resolved to the working tree to avoid false collisions. It also explicitly explains the meaning of a clean answer, the miss of agents with external transcripts, and separate 'unplaceable' handling, which is remarkably transparent.

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

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

The description is dense and each sentence carries intent: scoping, when to call, why, internal resolution logic, and limitations. It is slightly long but every clause supports efficient use of the tool, so it counts as well-structured rather than bloated.

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

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

For a tool with no output schema and no annotations, it does a strong job of covering the context and semantics of the result: what counts as a collision, what a 'clean answer' means, and why false negatives may happen. It never spells out the exact response shape, but the behavioral caveats and safety-guided intent are well documented. Minor gap remains in explicit return shape.

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 coverage is 100%, and the property's own description already explains the normalization and the `git rev-parse` recommendation. The overall tool description does not add parameter-specific guidance beyond this, but it also does not need to because the schema is very clear. Baseline is 3 for high coverage with no additional parameter detail in the text.

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 states the tool's specific purpose: detecting whether two agent sessions live in the same git working tree and branch, from any installed harness. It also says it's the call to make before git add, commit, or rebase, which gives clear identity. However, it never names sibling alternatives to differentiate itself, so it stops short of the strongest version of this criterion.

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 call the tool: before `git add -A`, before commit, and before rebase, with the shared-index rationale. It also gives important exclusions and caveats, such as 'a clean answer says only that nothing was found in what is readable' and that unreadable transcripts are not considered. It does not explicitly describe when to choose a sibling tool, but the usage context is clear and substantial.

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?

With no annotations provided, the description carries the full burden, and it does so well: it discloses that file contents are never returned, explains provenance semantics (`recorded` vs `from a command` and the possibility that the command never completed), and states the output scope (session, agent, paths, timestamps).

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 main purpose is front-loaded, and caveats follow in a logical order. There is slight redundancy between 'with the session each came from' and later 'each line names the session and the agent it came from', which prevents a perfect conciseness 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?

For a read-only tool with no output schema, the description is complete: it tells the agent what to expect (sorted paths/timestamps, provenance, no contents), how broadly it searches, and when to use it. There are no required parameters and the schema covers optional ones.

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 applies. The description adds no parameter-level detail beyond reinforcing the general use case; it does not explain `limit`, `project`, or `contains` beyond the schema. This is acceptable because the schema fully documents them.

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?

Description opens with a specific verb and resource: 'Which FILES other agent sessions have written or edited recently'. It adds delimiting constraints ('Paths and timestamps only — never file contents', 'newest first', 'spans every installed harness') that make it clearly distinct from content-search or git-history siblings.

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?

Ends with an explicit use case: 'Use it to see what another session has already touched before you edit the same area.' It does not name alternatives or state when not to use it, but the intended context is clear enough for an agent to select it appropriately.

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?

With no annotations, the description carries the behavioral burden, and it excels: it discloses that only metadata is returned, that all harnesses are read, that 'working' status is never reported, that silence means either crashed or idle, and that it works with Mnemosyne OS closed. These are non-obvious behaviors that materially affect how an agent interprets results.

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

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

The description is front-loaded with purpose and scope, then moves to return fields, usage, the critical caveat, and an environment fact. Each sentence adds information that is not inferable from the schema or tool name, with no filler or repetition.

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 metadata tool with no output schema and no annotations, the description covers the essential ground: input semantics, return field list, cross-harness scope, when to use it, how to interpret liveness, and an environmental constraint. There are no obvious gaps that would cause an agent to misuse it.

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

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

The schema already documents all three parameters, so the baseline is 3. The description adds meaningful interpretation: the limit is per-harness with a rationale, the project filter is meant for repository-folder scoping, and live_only relies on a recency window printed in the answer.

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 subject—other coding-agent sessions on this machine—and clearly states the source (transcripts harnesses write to disk) and the deliverable (metadata only). It also distinguishes itself by saying it reads every installed harness, not just the agent's own, which separates it from the agent-related 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?

It gives an explicit trigger: 'Use it before you touch shared state,' and explains the cross-agent visibility that makes it relevant. It does not name alternative sibling tools or state when not to use it, so it stops short of full usage branching, but the context is clear.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure print and does it thoroughly. It reveals the RAG pipeline internals (deeper retrieval, lexical fusion, re-rank), the latency (~30s), and the fact that prose is a model rewording, not verbatim memory. It also warns to always check sources before trusting the answer. No contradiction with annotations exists because none are present.

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

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

The description is dense and front-loaded: the first sentence states the core purpose; subsequent sentences add pipeline, latency, and trust caveats. There is slight redundancy in repeating the retriever claim ('better RETRIEVER' and 'reach for it whenever you need to find something'), but all sentences earn their place given the important caveats.

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 there is no output schema and no annotations, the description is remarkably complete. It tells the agent what to expect (prose plus a Sources list), how long it might take, what question types work well, and how to responsibly use the output. Missing only trivial details, such as explicit error behavior, which are not necessary for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already fully documents both parameters, including the scope_denied behavior for unrecognized vaults and the 'ask a knowledgeable colleague' guidance for the question. The description itself adds no parameter-specific detail beyond general 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 ('Ask'), a resource ('Mnemosyne'), and a concrete outcome ('a SYNTHESIZED prose answer grounded in the vault, PLUS the chronicles it drew on'). It also explicitly differentiates itself from sibling mnemosyne_query by claiming to be the better retriever and noting it is slower. There is no ambiguity about what the tool does.

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

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

The description gives explicit when-to-use guidance: 'reach for it whenever you need to find something' and 'Best on "why / who / how" questions spanning many memories'. It also names mnemosyne_query as the faster alternative and instructs users to fetch sources with it when exact quotes are needed. It includes a clear when-not-to-trust warning: never quote the prose; check the sources first.

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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the state is whatever the agent declares, that the host prints time since last call, that the card goes quiet without regular updates, that the response may contain a human message to act on, that the app window must be open, and that nothing persists to memory. This is rich behavioral context far beyond the 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 compact, front-loaded with the core purpose, and every sentence earns its place: when to call, what declaring state does, what the answer contains, the app-window prerequisite, and the no-memory limitation. It avoids repeating schema details and contains no 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 tool with six parameters and no output schema, the description is complete: it covers call timing, state semantics, response handling, prerequisites, and non-persistence. The one detail not repeated in the narrative, the 'closed' state removing the card, is fully documented in the schema, so no necessary information 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 fully documents all six parameters, including enum meanings for state. The description adds narrative context about when states are used and what effects they have, but it does not add new syntax, format constraints, or parameter-level details 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 states a specific verb and resource: updating your own status card in the cockpit. It gives concrete occasions for each state (starting a task, needing the human, stuck, done), and the 'card, not a note' line clearly separates it from memory-oriented siblings like mnemosyne_query or mnemosyne_ingest.

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

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

It explicitly says when to call: at task start ('working'), when needing the human ('waiting'), when stuck ('blocked'), and when done ('done'). It also gives behavioral cues like the card pulsing and taskbar flashing. It does not name a specific alternative sibling tool, but 'nothing is stored in memory; this is a card, not a note' acts as a soft exclusion.

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?

With no annotations, the description carries the burden of behavioral disclosure. It explains that bridges are produced during offline/idle-time scans, depend on being 'enabled in Settings', contain a dbs score and raw cosine similarity, and can legitimately be empty. This is strong contextual transparency, though it stops short of explicitly addressing side effects or access 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?

The description is dense but not padded, and the core action is front-loaded. The 'offline (idle-time)' phrasing is repeated later with 'runs while the machine is idle', which is a minor redundancy. Overall, every sentence contributes meaningful context about purpose, output, usage, and edge behavior.

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

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

For a list tool with four optional parameters and no output schema, the description is complete: it names the returned fields (bridge, dbs, raw cosine similarity, excerpts), explains when an empty result is expected, and gives concrete usage purposes. An agent has enough information to invoke it correctly and interpret its 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?

The input schema already has 100% description coverage, so the baseline is 3. The tool description adds useful conceptual meaning beyond the schema by explaining what a bridge is, that it links two chronicles possibly across vaults, and what dbs represents. This directly enriches min_dbs and chronicle_id even though limit and session_id 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?

The description opens with a specific verb and resource: 'List the connections Mnemosyne's Dream State engine discovered between memories during its offline (idle-time) scans'. It clearly identifies what the tool returns, the underlying concept, and differentiates it from the sibling tools by focusing on dream-derived bridge associations rather than queries, ingestion, or position tracking.

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

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

It gives explicit use cases: 'surface non-obvious associations', 'audit whether dreamed connections are insightful or noise', and 'seed creative exploration'. It also explains that an empty list is normal, which prevents misinterpretation. It does not explicitly name alternative sibling tools or state when not to use it, but the usage context is clear.

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?

There are no annotations, so the description must carry the safety/behavior burden. It does disclose that the value is a 'last known' position saved by an agent or cockpit, implying it may be stale or persisted, but it does not explicitly state that the call is read-only or describe behavior when no position exists.

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 short, front-loaded sentences with no filler. The first sentence states what the tool returns, and the second gives the primary use case. Every word 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 read tool with no output schema, the description adequately explains what is returned ('phase and description') and when to use it. It could be slightly more complete by mentioning behavior if no saved position exists, but the core guidance is sufficient.

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 description coverage is 100% and the resonance_id parameter is already documented with examples. The tool description does not add further parameter-level nuance beyond reinforcing that the id is for a specific Resonance, so the schema is doing 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 uses a specific verb ('Get') and resource ('current position of a specific Resonance'), and clarifies the meaning of 'position' as 'the last known phase and description saved by an agent or the cockpit.' This makes it easy to distinguish from siblings like mnemosyne_update_position and mnemosyne_resonances.

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 context: 'Use this at the start of a session to know exactly where work left off.' It does not explicitly mention alternatives or when not to use it, but the stated use-case is clear enough to guide selection.

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?

With no annotations provided, the description carries the behavioral disclosure burden. 'Get' implies a read-only operation and 'recent git commits' conveys the data source, but the description does not explicitly state that the tool performs no mutations, nor does it describe the output fields, ordering, or failure modes. Adequate for a simple read tool, but not fully transparent.

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 clean sentences: the first states the action and resource, and the second gives the practical use case. There is no redundant wording or irrelevant context, and important information is 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?

The tool is relatively simple with only two optional parameters and no output schema. The description gives purpose and use case, but since there is no output schema it would benefit from clarifying what fields are returned (e.g., hashes, messages, dates). Still, enough information exists for an agent 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?

Both parameters are fully described in the input schema with defaults and example formats, so schema coverage is 100%. The description adds little parameter-specific meaning beyond the schema, so the baseline score of 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?

The description clearly identifies the operation ('Get recent git commits'), the specific resource ('Mnemosyne OS monorepo'), and the intended context (understanding recent changes, active phase, shipped features). This differentiates it from the sibling tools, which focus on other Mnemosyne subsystems.

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 when to use the tool: 'Use this to understand what changed recently, which phase is active, and what features were shipped.' This gives the agent clear invocation context, though it does not name specific alternatives or exclusion conditions.

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

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

With no annotations, the description carries the full burden. It discloses key traits: persistence ('Stored permanently') and indexing for retrieval. It also warns about confirmation via mnemosyne_vaults in the vault parameter. However, it does not mention side effects like idempotency, duplicate handling, or any return value. Since it's a write tool, permanence is the most critical trait, so it's reasonably covered, but gaps remain.

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?

Three sentences, zero waste. The first sentence defines the action and purpose, the second states permanence and indexing, the third gives timing guidance. Information is front-loaded and each 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 3-parameter write tool with full schema coverage and no output schema, the description explains the outcome (permanent storage, indexing) and provides usage context. It does not describe the response format, but that's acceptable given the simplicity. It also hints at prerequisite checks (vault existence) via the schema. The description is sufficiently complete for an agent 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 the baseline is 3. The description adds minimal parameter guidance beyond schema—mostly repeating that content should be self-contained, which is already in the schema. It does add a hint about using spine_type for semantic boosting, but that's more about behavior than parameter semantics. The description does not materially improve on the schema's documentation.

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 ('Persist') and resource ('Mnemosyne OS vault'), with concrete example content types (decision, architecture note, etc.). It clearly distinguishes itself from sibling tools like mnemosyne_query (read) and mnemosyne_vaults (list vaults) by being the write operation for memories.

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

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

Provides explicit timing guidance ('at the END of a meaningful work session, or whenever you reach a decision...'), which is actionable. It also implies when not to use it (for trivial content) and implicitly points to alternative read tools via context, though it doesn't explicitly name them. Could name mnemosyne_query as the retrieval alternative for completeness.

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?

With no annotations, the description carries full responsibility for behavioral disclosure. It covers freshness semantics (results are as fresh as the last Scan, never fresher), the meaning of 'No radar', the requirement that the app be running while Pheme may be closed, and the conditional presence of tiers. This is unusually transparent.

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

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

The description is dense but every sentence earns its place: what is returned, freshness, usage, the 'No radar' edge case, and runtime prerequisites. It is front-loaded with the core purpose and contains no 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?

There is no output schema, but the description explains the main return elements: the scan time, threads, topic scores, and tiers, plus the special 'No radar' message. For a low-complexity two-parameter read tool, this is complete enough for an agent 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 coverage is 100%, so the baseline is 3. The description adds meaningful context for 'tier' by explaining that it represents how much substance the human can bring to a thread and only appears only after the Mnemosyne pass. It does not add anything about 'limit', but the schema already documents that clearly.

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 ('Read') and a precise resource ('what the human's Pheme radar last found'), then details the contents: fresh threads, topic scores, and tiers. This clearly distinguishes it from sibling tools like mnemosyne_pheme_watch, which presumably manages the watch list rather than reading radar results.

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

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

It explicitly says to use this tool 'to find threads to draft a reply for' and explains how to handle the 'No radar' case. It does not explicitly list alternatives or when-not-to-use conditions, 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?

There are no annotations, so the description carries the full burden, and it does so richly. It discloses ownership semantics ('The lists are THEIRS'), failure behavior ('an op that would empty a list is refused'), per-op outcomes, receipt side effects, the prerequisite that the app must be running, and the guarantee that nothing posts anywhere.

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 dense: every clause earns its place by adding a distinct behavioral fact. It front-loads the primary action before providing usage, exclusions, and side effects. Minor splitting of the first long sentence would improve readability, but it is not bloated.

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 annotations and no output schema, the description fully compensates: it covers what the tool does, when to use it, what it deliberately does not do, failure modes, per-operation reporting, receipt behavior, and runtime prerequisites. An agent has enough context to invoke it correctly and anticipate consequences.

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

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

The schema already describes all parameters: ops array, op enum, kind enum with meaning, and value max length. The description adds useful context about how these operations behave, but it does not substantially change or extend parameter meaning beyond the schema's 100% coverage.

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

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

The description states a specific operation and resource: 'Put a subreddit, a Hacker News search query or a topic on the human's Pheme radar ... or take one off.' It clearly distinguishes what the tool does from siblings by adding 'It does not scan and it does not post.'

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 names when to use the tool with a concrete example: 'Use it when a conversation has found a community worth watching.' It also states non-uses ('It does not scan and it does not post'), though it does not explicitly name an alternative tool such as mnemosyne_pheme_radar for viewing the radar.

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?

There are no annotations, so the description carries the full behavioral burden — and it does so thoroughly. It discloses the ranking mechanism (vector similarity fused with BM25, weighted by spineType), warns that scores are not confidence indicators ('a miss and a hit come back with indistinguishable scores'), and discloses a concrete retrieval weakness on rare literal terms with a measurement date. This is far beyond the bare minimum with zero annotations present.

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

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

The description is long but every sentence earns its place: purpose, rank-and-cite framing, sibling routing, and a critical score-confidence warning are all substantive. It is front-loaded with the primary purpose and uses ⚠️/⛔ markers to signpost warnings. Minor redundancy (the 'find something' phrasing repeats the ask-routing point) keeps it just short of perfect.

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 or annotations, the description covers the essential context an agent needs: what comes back, how results are ranked, how to interpret scores, and which sibling to choose instead. It does not describe the exact return fields of a result object, which would be a nice addition given the absent output schema, but the tool is otherwise complete enough to 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 description coverage is 100%, so the baseline of 3 applies; the schema itself documents all five parameters (query examples, limit caps, vault token normalization, content-size limits, spine-type filtering). The description adds only modest parametric context — e.g., that ranking is weighted by spineType — but does not materially deepen per-parameter meaning 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 opening line states a specific verb and resource ('Raw chronicle search in a Mnemosyne OS vault') and enumerates exactly what is returned (architecture notes, code, decisions, sessions, git history). It also distinguishes itself from siblings by emphasizing that nothing is rewritten and the source text comes back verbatim.

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

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

It gives an explicit when-to-use ('this is what to use when you need the source text verbatim, e.g. to quote it or to write documentation from it') and a named alternative with a rejection condition ('prefer mnemosyne_ask even when you only want its sources', with a measured date explaining why). This is textbook when/when-not/alternatives guidance with no ambiguity.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only list operation and states the returned fields (name, status, last position, last activity), which gives an agent some idea of the output. But it leaves ambiguity around whether the list includes only active or all resonances, and does not mention pagination, error cases, or any side effects.

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 three sentences with no fluff: the first sentence states the action and resource, the second lists the returned attributes, and the third gives the use case. It is front-loaded and every sentence adds value.

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

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

The tool is simple (no parameters, no output schema), but the description alone must be enough for an agent to know exactly what the call returns. It names the fields, but the ambiguous wording of 'active' means the boundary of the returned set is unclear. Also, many sibling tools revolve around resonance position and querying, so a more explicit statement of how this list tool relates to them would substantially improve completeness.

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 tool has zero parameters, so there is nothing for the schema or the description to elaborate. The description focuses on the output rather than parameter meanings, which is appropriate for a no-parameter tool, and the baseline for 0 parameters is 4.

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

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

States the specific action 'List' and resource 'Resonances' and explains what they are (cognitive workspaces). It also lists the returned fields. However, 'active' is ambiguous—whether the tool only lists active resonances or all resonance entries with an active/paused status—and it does not explicitly differentiate itself from sibling tools like mnemosyne_query or mnemosyne_get_position.

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 use case: 'Use this to understand what projects are currently active and where each one stands.' This provides clear context for when to call it, though it does not mention when not to use it or point to an alternative sibling tool.

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

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

With no annotations provided, the description carries the full behavioral burden. It compensates well: it states the operation is inspection ('Inspect', 'audit'), reveals ordering ('newest first'), clarifies that counts remain whole-vault when filtering by spine_type, and notes the taxonomy tree is optional. It does not explicitly assert non-mutating behavior, but the inspection framing and absence of side effects make it reasonably transparent.

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 sentences deliver the main output, the use cases, and the connection to mnemosyne_query with no wasted words. The first sentence front-loads the core behavior and key ordering detail; the second covers intended usage. The 'chronicle → spine' notation is compact but understandable in context.

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?

There is no output schema, so the description reasonably explains what is returned: assignments (newest first), whole-vault per-spine counts, and the optional taxonomy tree. It also clarifies that filtering by spine_type does not change the whole-vault counts. Combined with the 100% schema parameter coverage for a no-required-parameter tool, this is enough for an agent to call it correctly.

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

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

Schema description coverage is 100%, so all five parameters are already documented with defaults and semantics. The description adds context by mentioning the optional taxonomy tree and the idea of discovering taxon ids for use in mnemosyne_query, but it does not add new meaning to the parameters beyond what the schema already provides. 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?

The description opens with a specific verb and resource ('Inspect how Mnemosyne classified its memories: chronicle → spine assignments') and clearly enumerates the distinct outputs: newest-first assignments, whole-vault per-spine counts, and the optional global taxonomy tree. It also differentiates from the sibling mnemosyne_query by framing this as an audit/composition tool and mentions producing the taxon ids to pass into mnemosyne_query.

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 concrete trigger contexts: audit auto-classification quality, inspect a vault's composition at a glance, or discover taxon ids for use as a filter in another tool. It does not explicitly list when NOT to use this tool or name a sibling to switch to, but the use-case list is strong enough that an agent can infer appropriate versus inappropriate invocations.

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?

With no annotations, the description carries the full disclosure burden and does substantial work: it explains that writes route through the widget's own store, that what is filed is exactly what the human sees, and that behavior differs between dev installs with a daemon and npm installs without one. It omits permissions, idempotency, and success-response shape, but for a write tool it is unusually transparent.

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

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

The description is dense but efficiently front-loaded with the action, the trigger, and the key list-handling rule; environment details and sibling routing are placed later where they belong. It earns its length, though the LIST_NOT_FOUND sentence is tangled and could be tightened.

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

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

For a tool with no output schema, the description covers why/when to use it, how to discover or create lists, persistence through the widget store, environment requirements, and alternatives for related operations. It does not explicitly describe the success return value or downstream effects on existing tasks, which is a modest gap, but the overall context is strong.

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

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

Schema description coverage is 100%, and the schema already documents each parameter in detail, including list default/error behavior, hex color, task group semantics, the 300-character limit, and create_list's default. The description adds operational framing rather than new parameter meaning, and its LIST_NOT_FOUND wording slightly muddies the list-omission semantics, so the 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 opens with a specific verb and resource: 'Put tasks into the human's To-do backlog,' adding ordering and grouping semantics. It also distinguishes itself from siblings by pointing to mnemosyne_todo_list, mnemosyne_todo_update, and mnemosyne_todo_lists for read/change operations, so an agent can tell them apart without inspecting 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?

It gives an explicit trigger ('when a conversation has settled WHAT to do') and warns never to assume a default list, plus points to sibling tools for reading or changing the backlog. However, the sentence about calling without `list` to get a LIST_NOT_FOUND answer is convoluted and sits awkwardly against the schema's statement that omitting `list` selects the first original list, so the guidance is not perfectly crisp.

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?

With no annotations provided, the description carries the full burden and does so thoroughly: it is a read-only scope ('todo:read'), reads from a file via a daemon in dev installs, returns IDs needed for later mutation, and explains that results always state how many matched and were cut. This goes well beyond the input 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 front-loaded with the core purpose, then adds targeted warnings, use cases, and environment context. Every sentence earns its place; the length is justified by the valuable guidance it conveys.

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 tool with three optional parameters, no output schema, and no annotations, the description covers what is returned (lists, tasks, IDs, counts), when to use it, and operational prerequisites. Nothing essential is missing for an agent to select and 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 list, limit, and include_done behavior. The tool description adds no additional parameter-specific meaning beyond what the parameter descriptions provide, so no upgrade is warranted.

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: 'Read the human's To-do backlog back: the lists that exist and the tasks in them.' It also names the distinguishing purpose of exposing task IDs for later mutation, and explicitly contrasts itself with mnemosyne_todo_update. This makes the tool's role unambiguous even among similarly named siblings.

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

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

It explicitly states when to invoke this tool: before mnemosyne_todo_update, when answering 'what is on my plate', and before adding a duplicate via mnemosyne_todo_add. It also provides environmental guidance about dev installs versus npm installs. The usage conditions are concrete and actionable.

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

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

With no annotations provided, the description carries the full disclosure burden and meets it: it reveals refusal conditions, the count of blocking tasks, that the host will not pick a destination, that original lists are permanently protected, and how the daemon vs app affects availability. This goes well beyond a generic 'manage' statement.

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 main purpose is front-loaded in the first sentence, and all subsequent sentences carry high-value behavior or refusal information. No filler or repetition of schema content. Despite its length, 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 moderately complex tool with one nested parameter, three operation types, and no output schema, the description covers all necessary context: operations, exclusions, refusal behavior, environment prerequisites, and scope. It even hints at the response ('you are told how many are in the way'). Nothing needed to call it correctly seems 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. The description adds meaningful extra semantics, notably that passing an empty string on an original list restores its localised default name, and that the host picks the next swatch when color is omitted. It does not deeply elaborate every parameter, but the schema already handles those details.

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 resource ('LISTS of the human's To-do backlog') and enumerates the concrete operations: create, rename/recolour, remove. It also explicitly separates itself from mnemosyne_todo_update, making the tool's scope unmistakable even among many 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?

States exactly when this tool is appropriate vs mnemosyne_todo_update ('change the shape of someone's workspace rather than the work in it'). Provides detailed pre-call conditions: lists containing tasks are never removed, original lists can be renamed but never removed, and environment requirements for dev vs npm installs. All conditions are actionable.

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

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

With no annotations provided, the description takes on the full behavioral burden. It discloses that removal archives by default and is restorable, that the batch applies as one save, that operations report their own outcomes, and that a stale id won't sink others. It also covers environmental constraints. Slight gaps like non-recoverable streak side-effects are left to the schema, but overall transparency is strong.

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

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

The description is dense but every sentence earns its place, covering scope, prerequisite, destructive behavior, atomicity, error isolation, environment prerequisites, and required scope. It is front-loaded with the core purpose and operation list, with no filler or repetition.

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 (nested ops array with multiple operation types) and lack of output schema, the description provides everything needed to call it correctly: task id sourcing, operation semantics, permanent deletion nuance, batch behavior, per-operation outcomes, environment constraints, and auth scope. The note that each operation reports its own outcome compensates for the missing output 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 the schema already thoroughly documents each field, including the op enum, permanent default, and field-specific behaviors. The description reinforces some key semantics (e.g., 'pass permanent: true only when...') but doesn't add substantial information beyond what the schema provides, keeping this at the 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 ('CHANGE') with a clear resource ('the human's To-do backlog') and enumerates the exact operations: edit, tick off, move, remove. It also implicitly distinguishes itself from siblings like mnemosyne_todo_add by framing this as modifying existing tasks and requiring ids from mnemosyne_todo_list.

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 instructs to call mnemosyne_todo_list first to obtain task ids, which is a critical prerequisite. It also clarifies when to use permanent: true (only when outright deletion is requested) and notes environment-specific daemon requirements. It doesn't explicitly name mnemosyne_todo_add as the alternative for creating new tasks, but the 'CHANGE' framing makes the boundary reasonably clear.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool is a mutation ('Update') and, notably, that this is 'persisted as a DECISION chronicle in the vault' — which hints at audit/immutability semantics beyond a simple field update. It does not state whether the write is append-only, idempotent, or requires certain permissions, but 'DECISION chronicle' adds meaningful behavioral context. A 4 is appropriate because the persistence trait is genuinely useful, but the description stops short of explaining side effects on prior positions.

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 sentences with clear front-loading of the verb, resource, and specific call timing. The second sentence's chronicle detail adds useful behavioral context without bloating. Every clause 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 three-parameter update with a full schema, the description adequately covers purpose, timing, and content. No output schema means return-value behavior is undocumented, but for an update tool this is less critical. The main missing context is what happens to an existing position (replaced, appended to a history, or stored as a new chronicle entry) — but the 'DECISION chronicle' phrasing partially covers this, so the overall package is solid but not 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 schema already documents all three parameters. The description contributes the grouping 'phase, current state, next steps,' which maps loosely to the 'phase' and 'position' parameters and clarifies the intended content. However, it doesn't add required-format guidance, examples, or relationship semantics beyond what the schema already says. Baseline 3 is correct when the schema carries full documentation.

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 ('Update'), a resource ('current position of a Resonance'), and the timing ('at the end of a session to record where you left off'). It also clearly distinguishes this from the sibling mnemosyne_get_position, which retrieves position rather than updating it. The only slight gap is that 'Resonance' itself is a domain term that isn't defined here, but the tool name and resource phrasing make the purpose clear.

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 context for when to call the tool: 'Call this at the end of a session to record where you left off — phase, current state, next steps.' It does not explicitly list alternatives or when not to use it, but the sibling contrast with get_position is implicitly clear because this tool writes and get_position reads. An explicit exclusion statement would improve the score.

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?

With no annotations, the description carries the full behavioral burden and handles it well: it discloses the token-versus-id distinction, the output fields, and the fact that unconfigured vaults are flagged and refused. It does not overtly state that the operation is read-only, but that is obvious from 'List' and the absence of destructive language.

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 three sentences with no filler: the first states purpose and output, the second gives the usage trigger, and the third clarifies the token/id pitfall and access constraints. It is front-loaded and 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 zero-parameter list tool with no output schema, the description is complete: it names the returned fields, explains when to call it, warns against the id/token confusion, and notes the configured-vault limitation. 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?

This tool has zero parameters, so the baseline is 4. The description goes beyond that baseline by explaining how its returned token should be used as the `vault` argument for other tools, which adds semantic value for the broader tool set even though this tool itself takes no inputs.

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: 'List the memory vaults this Mnemosyne OS exposes', and enumerates the returned fields (token, display name, chronicle count). This clearly differentiates it from sibling tools that query, ask, or ingest rather than enumerate vaults.

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

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

It gives an explicit invocation condition: call this first when unsure which vault to use or when the user names an unfamiliar memory store. It also provides downstream guidance by instructing the agent to pass the returned token, not the internal id, to other tools, and it states the configuration restriction on accessible vaults.

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