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

readOnlyHint already covers the non-mutating safety profile. The description adds useful behavioral context: the tool re-reads client-visible server instructions on connect and enumerates the content topic areas. It doesn't specify exact output shape, but for an informational no-parameter tool this is a minor gap rather than a serious omission.

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 efficient sentences front-load the action ('Re-read the server instructions') and then provide a compact, useful list of the contained topics plus a concrete call condition. No filler or repetition of the schema/annotations.

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 parameterless read-only about/info tool with no output schema, the description is complete: it says what the tool returns conceptually (server instruction text), what topics it covers, and when to invoke 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 input schema has no properties, so the zero-parameter baseline applies. There is nothing for the description to add about argument semantics, and the description doesn't invent any.

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 and resource: 'Re-read the server instructions,' and then enumerates exactly what those instructions cover (governance tenet, vault protection model, spine model, memory-work rules). This clearly separates it from the operational sibling tools like mnemosyne_memory_query or mnemosyne_vault_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 gives a concrete condition for calling: 'Most clients show this text on connect. Call it if yours did not, or to read it again.' That is an explicit when-to-use rule, and it implies the negative case (if it was already shown, no call is 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?

Beyond the annotations, the description discloses useful behavioral context: writes are routed through the widget's own store, so what is filed is what the user sees, and it explains the daemon difference between dev installs and npm installs. It does not contradict annotations and adds meaningful operational detail, though it omits error/return 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 description is well-structured: purpose first, then usage trigger, then the operational caveat, then sibling routing. Every sentence earns its place, and there is no filler or redundant restatement of schema details.

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 that the schema richly documents parameters and the description covers purpose, usage, storage behavior, runtime requirements, and alternatives, the tool is almost fully specified. The main gap is that there is no output schema and the description does not state what a successful call returns or how failures surface.

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

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

The input schema already covers 100% of parameters with detailed descriptions, including the ISO 8601 timezone caveat and the meaning of each optional field. The description adds no parameter-level detail beyond framing appointments and deadlines, so the schema carries the load and the 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 clearly states the action ('Put appointments or deadlines') and the resource ('the user's calendar, the Agenda widget on their canvas'). It also distinguishes itself from the sibling read/update/remove tools by explicitly directing readers to mnemosyne_agenda_list, mnemosyne_agenda_update, and mnemosyne_agenda_remove for those operations.

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 when a conversation names a date and time to remember', with concrete examples like meetings, deadlines, and 'add this to my calendar'. It also names alternatives for reading, changing, and removing appointments, giving clear routing guidance.

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

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

Annotations only declare readOnlyHint=true. The description adds substantial behavior beyond that: the calendar has no archive, removals cannot be undone, repeating events appear once with cadence and next occurrence, times are machine local, and daemon availability differs between dev and npm installs. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: core purpose and id relevance come first, then crucial behavioral caveats and environment requirements. No filler or repetition of schema content.

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

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

With no output schema, the description compensates by explaining key return characteristics: each appointment includes its id, repeating events show cadence and next occurrence, and times are local. It also covers operational prerequisites and safety implications, making the tool complete 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 schema already documents all four parameters including defaults and behavior. The description adds context about time windows and returned ids but no new parameter-specific meaning, 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 states a specific verb and resource: 'Read the user's calendar back: the appointments in a time window, each with the id you need to change or remove it.' It clearly differentiates this list tool from sibling mutation tools by explaining that it supplies the ids needed by mnemosyne_agenda_update and mnemosyne_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?

The description explicitly tells the agent when to call this tool: 'Call this before mnemosyne_agenda_update and mnemosyne_agenda_remove.' It also gives environment-specific guidance (dev install with headless daemon vs npm install needing the app running) and scopes access with 'Scope agenda:read.'

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

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

Beyond the destructiveHint annotation, the description details real consequences: no archive, removal is permanent, repeating appointments are removed as a whole series, and the response names each removed item. It also discloses environment-dependent daemon behavior, adding significant value.

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

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

The description is front-loaded with the core purpose and each sentence carries important caveat or usage information. It is longer than minimal, but every sentence earns its place; 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?

Despite lacking an output schema, the description explains what the response will name. It covers destructive semantics, repeating events, the id prerequisite, and the daemon/app runtime condition, making it fully actionable for an agent.

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 covers the single parameter at 100%. The description adds useful extra semantics: ids must be exactly as mnemosyne_agenda_list printed them in brackets hire up to 50. This goes beyond the schema's generic wording.

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: 'Remove appointments from the user's calendar.' It clearly distinguishes this tool from siblings by emphasizing id-only matching and contrast with archive-able To-do tasks.

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 procedural guidance: read appointments with mnemosyne_agenda_list first and pass the printed ids. It also warns against phrase-based removal. It does not spell out all exclusions or alternatives, but the context is clear enough for an agent to use it correctly.

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 indicate destructiveHint=true, but the description adds substantial behavioral context beyond that: it explains failure modes (refuses unreadable start/end times, refuses invalid cadence), the effect of null on recurrence (drops series end), and environment-specific behavior (works on dev install via daemon, needs app running on npm install). This goes well beyond the annotation flags and gives the agent a clear picture 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 a single, dense paragraph that front-loads the core purpose and then covers prerequisites, semantics, failure handling, and environmental notes. Every sentence carries operational weight; there is no filler. While it is longer than strictly minimal, the complexity of the tool justifies the length, and it is organized logically.

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 mutation tool with destructiveHint=true and no output schema, the description is remarkably complete: it covers the required id source, the patch semantics, failure conditions, recurrence behavior, and the dev/npm install difference. An agent can correctly invoke this tool for any intended change without additional clarification. The only minor omission is the exact response shape, but that is not needed given the absence of an 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 coverage is 100%, with each parameter having a detailed description (e.g., start time timezone semantics, null behavior for clearable fields). The description adds global semantics over the schema: 'A field you leave out is left alone, and passing null clears it' – a rule not per-parameter. It also clarifies the batch nature (up to 50 per call). This enhances the schema's guidance without redundancy.

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 clear verb ('Change') and resource ('an appointment already in the user's calendar'), then enumerates the specific actions (move, rename, add/drop reminder, start/stop repeating). It distinguishes itself from siblings like mnemosyne_agenda_add and mnemosyne_agenda_remove by focusing on modification, and it explicitly references the id source (mnemosyne_agenda_list), making its scope unambiguous.

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

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

The description explicitly states the prerequisite: 'It names appointments by the id from mnemosyne_agenda_list, so call that first.' It also explains the semantics of omitted fields (left alone) and null (clears), which tells the agent how to construct change requests. However, it does not explicitly contrast with add/remove or state when not to use this tool, though the sibling names make that inference easy.

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

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

The readOnlyHint is consistent and the description adds substantial non-obvious behavior: it reads transcript files from disk, needs neither Mnemosyne OS nor a token, resolves each directory to a working tree, and explicitly discloses that unreadable sessions are omitted and unplaceable sessions are listed separately. This gives an agent a clear model of what the tool can and cannot detect.

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, triggering scenarios, mechanism, and limitations. The critical before-commit guidance is front-loaded, and the later caveats about transcript readability and unplaceable sessions are important enough to justify the length.

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

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

The description covers when to use it, how it works, its data source, and its limitations, and the schema documents the only parameter. The one gap is the absence of output/response shape details, especially since there is no output schema; an agent cannot confidently predict the exact format of a collision report. This is minor but prevents a 5.

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 single optional `project` parameter is already fully described in the schema, including exact matching, path normalisation, passing `git rev-parse --show-toplevel`, and omission meaning 'check every project'. The description adds context about working-tree resolution but does not need to repeat the parameter details. Baseline 3 is appropriate given the 100% schema 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?

Opens with a specific verb and scope: 'Check whether two agent sessions are live in the same git working tree and branch right now, across every installed harness.' This is a distinct operation and clearly not the same as the sibling memory, todo, or agent tools. The title 'Check agent collisions' reinforces the same purpose without needing the schema.

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

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

Explicitly instructs when to call it: 'Call it before `git add -A`, before a commit, and before a rebase'. It also explains why via the shared git index, which helps an agent decide to insert this check into Git workflows. No near-sibling alternative is needed because the use case is unique.

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 provide readOnlyHint=true. The description goes well beyond that by explaining output shape ('Paths and timestamps only'), provenance labels ('recorded' vs 'from a command'), the reliability caveat ('may never have completed'), and scope ('spans every installed harness'). This is rich behavioral context that helps the agent interpret results safely.

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

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

Front-loads the core purpose and ordering, then packs necessary caveats (paths/timestamps only, provenance explanation, unreliability warning) into a compact paragraph. Every sentence earns its place; 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 list tool with three optional params and no output schema, the description explains what is returned ('paths and timestamps', session, agent, how it is known) and why it is useful. Combined with the fully documented schema, an agent has everything it needs to call and interpret 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% (limit, project, contains are all documented with types and constraints), so the baseline is 3. The tool description adds no additional parameter semantics beyond what the schema already says, which is acceptable.

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 ('List the files other agent sessions wrote or edited recently'), gives ordering ('newest first'), and names the exact use case ('see what another session has already touched'). It is clearly distinguished from siblings by targeting agent-written files, which no other mnemosyne_* tool covers.

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 says when to use it ('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 context is clear enough for an agent to select it over unrelated siblings like mnemosyne_memory_query or mnemosyne_agent_list.

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

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

The readOnlyHint=true annotation is confirmed and enriched by the description's 'Metadata only' and 'reads' language. More importantly, the description discloses non-obvious behavior beyond the annotation: it 'reads every harness installed here,' it works 'with the Mnemosyne OS app closed,' and it exposes the critical caveat that 'a crashed session and an idle one fall equally silent, so nothing here can tell you an agent is working' — telling the agent it must draw the liveness conclusion itself, not the tool.

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

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

The description is longer than minimal but every sentence earns its place: the core function leads, followed by the metadata list, the cross-harness scope, the usage trigger, the silent-session caveat, and the app-closed note. It is front-loaded with the primary purpose and well-ordered, though the metadata enumeration and caveat sentences could arguably be tightened without losing meaning.

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 filterable listing tool with three well-documented parameters, no required params, and no output schema, the description covers the essential ground: return metadata fields, scope, usage timing, and the liveness limitation. One minor gap is that the exact response structure isn't formally specified, but the description's metadata field list substantially compensates for the absent 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 baseline of 3 applies — the schema already documents limit, project, and live_only clearly, including the per-harness semantics of limit. The description only loosely reinforces this by mentioning 'how many files were touched' and 'when a line was last written,' which map to the live_only window, but it adds no new parameter syntax or format 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: 'List the other coding-agent sessions on this machine, read from the transcript files their harnesses already write to disk.' It enumerates exactly what metadata is returned (conversation name, project, git branch, model, last tool, files touched, last-write time) and scopes itself clearly ('Metadata only', 'every harness installed here, not just your own'). This distinguishes it from siblings like mnemosyne_agent_files and mnemosyne_agent_collisions without needing their 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?

The description gives an explicit when-to-use directive: 'Use it before you touch shared state.' It also explains the value proposition contextually ('you can see a session from a different agent working in your repository'). It does not name sibling alternatives or state when-not-to-use, but the practical trigger is clear 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?

Annotations are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the burden and does so richly: 'waiting'/'blocked' pulse the card and flash the taskbar, 'waiting' survives the harness ending the turn, the app prints time-since-last-call, the call requires the app window open, and nothing is stored in memory. It also discloses that the response carries the user's message.

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

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

Purpose is front-loaded and the guidance is organized logically from states to the 'waiting' caveat to behavioral notes. It is dense and somewhat long, with the 'waiting'/'blocked' behavior touched on in more than one sentence, but for a stateful tool this length is mostly earned.

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 mutation tool with no output schema, the description covers prerequisites ('Needs the app window open'), persistence behavior ('nothing is stored in memory', title given once), the return value (the user's message on the card), and the toolkit's rendering behavior. Nothing an agent needs to invoke it correctly appears to be 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%, so the schema already documents all seven parameters (states, title, detail, desktop, session, attention) with enums and defaults. The description restates the state vocabulary and adds usage context for 'waiting' and title persistence, but adds little semantic detail 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?

The description states a specific verb and resource: 'Update your own status card on the user's canvas, the cockpit.' It identifies the action clearly and distinguishes it from all sibling tools (agenda, todo, memory, agent tools) since it is the only one that writes to this status card.

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 maps each lifecycle moment to a state ('working' at start, 'waiting' when the user is needed, 'blocked' when stuck, 'done' on finish) and explicitly addresses the tricky case: send 'waiting' in the same turn as the question, right before stopping, because the harness only auto-handles permission prompts. This is explicit when-to-use guidance that no sibling conflicts with.

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

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

Annotations declare readOnlyHint=true, which the 'List' framing matches — no contradiction. Beyond the annotation, the description adds meaningful behavioral context: an empty result is a normal state rather than an error, and data only exists if the idle-time engine has run and the user enabled it in Settings. This helps the agent avoid misinterpreting empty responses or retrying unnecessarily.

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?

Four sentences, each earning its place: what the tool lists, what a bridge contains, when to use it, and what empty/normal behavior looks like. The core purpose is front-loaded and there is zero filler or redundancy with the structured fields.

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 here, the description carries the burden of describing return values and does so adequately (score, cosine similarity, excerpts of both sides). It also covers data availability and empty-result semantics. The only notable gap is not differentiating the tool from the similarly named mnemosyne_resonance_list sibling, which an agent would benefit from knowing about.

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 documents all four parameters (limit with default/cap, min_dbs range, session_id, chronicle_id). Per the baseline rule, the description need not repeat them; it adds indirect value by explaining what a bridge contains, which clarifies the meaning of min_dbs, but provides no parameter-specific guidance beyond the schema.

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

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

The description opens with a specific verb and resource: 'List the connections the Dream State engine found between memories while the machine was idle.' It further defines what a bridge is (two memories with a Dream Bridge Score, raw cosine similarity, and excerpts), which disambiguates it from siblings like mnemosyne_resonance_list by attributing the data to the idle-time Dream State engine.

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 use cases: 'surface associations the memory made on its own, to audit whether they are insightful or noise, or to seed creative exploration.' It also sets the expectation that an empty list is normal and explains the data depends on the user enabling the engine in Settings. However, it never names the closely related sibling mnemosyne_resonance_list or states when that alternative should be preferred, so exclusions are missing.

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?

Read-only is already in annotations, but the description adds critical behavior: commit fields, newest-first ordering, config/scope failure reporting instead of empty list. This tells the agent what to expect and how to interpret 'no commits' scenarios.

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?

Four dense sentences with the main action first, then behavior, constraints, and routing. No filler or repeated schema information.

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

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

With no output schema, the description compensates by specifying the return shape (hash, subject, author, date, newest first) and failure behaviors. Scope, configuration, and alternative usage are covered, making it complete for a simple read 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?

Schema description coverage is 100%, so the baseline is 3; limit and since are fully documented in the schema. The description adds no extra parameter-level detail beyond that, but it also doesn't need to.

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 recent commits from the git repository') and states the exact output fields and ordering. It distinguishes itself from mnemosyne_memory_query by noting that tool covers reasoning behind a change, so an agent can pick correctly.

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

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

It explicitly routes to mnemosyne_memory_query for the reasoning behind a change, giving a when-not alternative. It also states the tool is fixed to the configured checkout and requires monorepo:read scope, so agents know when it is usable and what failure looks like.

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, so safety is covered. The description goes beyond by disclosing performance (up to 30 seconds), the nature of the prose (a model rewording, so quote sources instead), and instructing to verify sources before trusting the answer. This adds rich, non-obvious behavioral context that helps the agent set expectations.

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 yet dense, with each sentence serving a distinct purpose: main action, pipeline details, usage guidance, performance caveat, and source-trust warning. It front-loads the core purpose and avoids fluff, making it efficient for an agent to parse.

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 no output schema, it fully describes the output (prose + sources), performance characteristics, and trust considerations. It also explains why to use the Sources list, covering all the information an agent needs to invoke and interpret the result 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% for both parameters, so the schema already documents them. The description adds extra nuance on the question parameter ('plain language, the way you would ask a colleague who knows the material') and clarifies vault behavior, providing value beyond the schema without being redundant.

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 (the vault), and the exact output (prose answer plus sources). It explicitly differentiates itself from siblings like mnemosyne_memory_query by positioning itself as the better retriever, leaving no ambiguity about what it 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?

It gives explicit when-to-use guidance: 'reach for it whenever you need to find something' and identifies its sweet spot ('why, who and how questions that span many memories'). It also names the alternative (mnemosyne_memory_query) for fetching sources, so the agent knows exactly when to choose this over a sibling.

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

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

The annotations are thin (readOnlyHint=false, destructiveHint=false), so the description carries the full disclosure burden, and it delivers the single most important behavioral fact: 'stored permanently and indexed for every future agent to retrieve.' This irreversibility warning is then reinforced in the vault parameter ('Ingest is permanent'), giving agents the clear risk cue they need before calling a write tool. No annotation contradiction arises — a permanent additive write is consistent with destructiveHint=false.

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 filler: the action and acceptable content types are front-loaded, the permanence trait comes second, and the when-to-use guidance closes. Every sentence earns its place and none repeats what annotations or schema restate, making this an ideal length for agent consumption.

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-required-parameter write tool with 100% schema coverage, the description plus schema covers purpose, when to use, target vault semantics, content formatting, and the permanence risk almost completely. The only gap is the operation's response shape (no output schema exists, and the description never says whether the ingest returns a confirmation or identifier), which would help an agent verify successful persistence.

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 parameter descriptions are exceptionally rich — the vault parameter explains token formatting, defaults, scoped tokens, and the permanence caveat, while spine_type maps enum values to usage contexts. Per the baseline rule, the schema already does the heavy lifting, and the main tool description adds no parameter-level meaning of its own, so a 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+resource pair, 'Write a memory into a vault', and enumerates the exact content kinds it accepts (decision, architecture note, debug finding, session summary). The phrase 'stored permanently and indexed for every future agent to retrieve' implicitly differentiates this write tool from the read-only siblings like mnemosyne_memory_query and mnemosyne_memory_ask, so an agent can tell them apart without opening their 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?

The description gives explicit when-to-use context: 'at the end of a meaningful work session, or whenever a decision is reached that someone will want to recall later.' The vault parameter additionally embeds a prerequisite ('confirm the vault exists with mnemosyne_vault_list before writing anywhere new'). However, it never names read-side or task alternatives (memory_query, memory_ask, todo_add) or states when NOT to use it, so it stops just short of full exclusionary 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?

With readOnlyHint true, the description still adds critical behavioral context: 'Nothing is rewritten,' the ranking uses vector similarity fused with a local BM25 channel, and the score is not a confidence value because hits and misses return similar numbers. This goes beyond the annotations and helps the agent correctly interpret results. No contradiction with annotations.

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

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

Each sentence earns its place: purpose, when-to-use, ranking mechanics, alternative routing, and score interpretation. The most important usage guidance is front-loaded. Though it is a longer description, it is dense with actionable information 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 five-parameter tool with no output schema, this description is remarkably complete. It explains what results look like ('word for word'), that snippets are truncated with size hints, how ranking works, and how to interpret the score. Combined with the richly described input schema, an agent has enough to select and 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?

Schema description coverage is 100%, so the schema already documents all five parameters thoroughly, including examples for query and vault token semantics. The description itself does not add parameter-level details, but it doesn't need to; the baseline of 3 applies since the schema carries the load. The description's ranking and score caveats are behavioral, not parameter 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 states a specific verb and resource: 'Search a vault and get the matching memories back word for word.' It names exactly what content is returned (notes, code, decisions, session summaries, commit history) and explicitly separates this tool from mnemosyne_memory_ask. This is unambiguous and distinguishes it from siblings without opening their 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?

The description gives explicit when-to-use guidance: use it when you need source text itself, to quote it, or to write documentation from it. It also gives an explicit alternative: prefer mnemosyne_memory_ask 'to FIND something rather than quote it,' explaining why because that tool re-ranks and catches rare literal terms. This is clear routing guidance.

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

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

The description adds substantial behavioral context beyond the readOnlyHint annotation: it explains the freshness of results, the 'No radar' condition, the prerequisite of the app running, and the structure of the answer (leads with scan time). This fully discloses the tool's behavior and is consistent with the annotations.

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

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

The description is about 100 words, but every sentence adds value: it explains the tool's purpose, output semantics, freshness, usage, and prerequisites. It is front-loaded with the core purpose and structured logically, though slightly longer than strictly necessary for a simple read operation.

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 has no output schema and only two optional parameters, the description covers all essential information: what results are returned (threads with scores and tiers), the freshness caveat, the 'No radar' handling, and the runtime prerequisite. An agent can confidently decide when to call it and 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?

With 100% schema description coverage, the baseline is 3, but the description enriches the tier parameter by explaining what a tier means ('how much substance they can bring to that thread'). It also clarifies the output includes topic scores and tiers, which helps agents decide whether to filter by tier. The limit parameter is well-covered by the schema alone.

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

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

The description clearly states the verb 'Read' and the resource 'Pheme radar', and explains what it returns: fresh threads from subreddits and Hacker News queries. It also distinguishes itself from siblings like mnemosyne_pheme_watch by focusing on reading results rather than setting up watches, making the purpose unambiguous.

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

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

The description provides a clear use case ('Use it to find threads to draft a reply for') and contextual conditions like the need for the app running and the 'No radar' edge case. However, it does not explicitly mention alternatives or when not to use this tool, though the read/watch distinction is implicit.

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

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

The description adds substantial behavioral context beyond the annotations: operations that would empty a list are refused, each operation reports a specific outcome ('done, already there, not there, refused'), the user receives a receipt naming the agent and what changed, and the tool scans/posts nothing. This fully discloses side effects, refusal behavior, and reporting, with no contradiction to 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 front-loaded with the core action and then provides necessary behavioral details. A few sentences are somewhat narrative ('Pheme is their reputation cartridge...'), but each sentence contributes useful context about outcomes, receipts, or prerequisites. It is appropriately sized for a mutation tool with one nested parameter.

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 tool with no output schema, the description is complete: it explains the action, domain, side effects, refusal behavior, return-like outcome reporting, and runtime prerequisite. An agent has enough guidance to select and invoke the tool correctly without needing additional context.

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 the schema already documenting the op/kind/value fields and their enums. The description adds domain framing (Pheme radar, lists, outcomes) but does not introduce additional parameter syntax or constraints. Baseline 3 applies because the schema carries the parameter 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 states a specific action ('Add... or take one off') with a specific resource (subreddits, Hacker News search queries, topics on the Pheme radar). It also defines the domain concept 'Pheme' and distinguishes the edit-and-remove operation from mere viewing, which likely separates it from sibling mnemosyne_pheme_radar.

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 a clear trigger condition: 'Use it when a conversation finds a community worth watching.' It also provides a prerequisite ('Needs the app running, though Pheme itself can be closed'). It does not explicitly name alternative tools or state when not to use it, but the usage context is clear enough.

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

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

Beyond the readOnlyHint annotation, the description discloses the exact return fields and the distinctive unknown-id behavior: a plain-words response that names the update tool, so a blank history is distinguishable from a failed call. No contradiction with annotations 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?

Three purposeful sentences front-load the operation and read-only nature, then add return details and fallback behavior. Every clause earns its place, with the alternative routing placed at the end.

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-parameter read tool with no output schema, the description fully specifies what the response contains and how the one edge case behaves. An agent has everything needed to decide when to call it and to interpret the result 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 fully documents the single required resonance_id parameter with an example, so the schema carries the parameter-meaning burden. The description reinforces that the id selects a prior saved resonance but adds no new parameter syntax or format 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?

The description opens with a specific verb and object: 'Read where one resonance was left,' then enumerates what is returned. It differentiates itself from siblings by explicitly referencing mnemosyne_position_update and mnemosyne_resonance_list as related alternatives.

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 routes the agent to mnemosyne_resonance_list when the id is unknown, and explains that a missing-id response points to mnemosyne_position_update. This gives clear when-to-use and when-not-to-use guidance beyond the read-only positioning.

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

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

The description discloses a meaningful behavioral trait beyond the annotations: the output is 'stored as a DECISION memory in the vault.' This tells the agent the write is persistent and goes to a specific memory category. The description does not contradict the readOnlyHint=false and destructiveHint=false annotations, and adds value without needing to repeat them.

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

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

The description is two sentences, with the core action front-loaded and the usage trigger immediately following. Every sentence earns its place: the first defines purpose and content, the second gives the usage moment and storage semantics. No filler or restatement of the tool name.

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 three-parameter write tool with no output schema, the description covers the what, when, and where-it-stored aspects. It does not explicitly state whether the position is overwritten or appended, but the tool name 'position_update' and required resonance_id make the update semantics reasonably clear. The description is adequate 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%, and each parameter already has a descriptive schema comment. The tool description adds a light mapping by mentioning 'phase, current state, next steps' which maps to phase and position, but it does not materially expand on the schema's existing parameter descriptions. 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 states the verb ('Record') and the resource ('a resonance') and exactly what is recorded: phase, current state, next steps. It also distinguishes this position-saving action from siblings like mnemosyne_position_get or memory_ingest by framing it as a session-end bookmark, not a fetch or generic memory write.

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 guidance on when to call the tool ('Call it at the end of a session'), which provides clear context. It does not name specific alternatives or when not to use it, but the instruction is unambiguous enough for an agent to know the intended trigger.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavioral details: there is no status filter, results are capped at 30 candidates, and an empty result is 'written in words' rather than returned as an empty array. It also explains what each entry carries (id, last phase, minutes since moved, memory id), which is valuable context given there is no output schema.

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

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

The description is front-loaded with the tool's purpose and scoping ('List the resonances recorded in the default vault'), then adds concise, meaningful details about result contents, limits, and empty behavior. Every sentence earns its place, and the sibling-routing guidance is compactly placed at the end without padding.

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

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

The description is complete for a parameterless read-only list tool: it explains the domain concept, default scope, result fields, candidate limit, empty-result representation, and how to follow up via sibling tools. With no output schema and no parameters, the description carries the full burden of telling an agent what will happen and what it will receive, and it does so thoroughly.

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 100% schema description coverage, so the description has no parameter semantics to add. The description instead uses the parameter-free space to clarify the result shape and domain concept, which is appropriate for a no-argument list tool. The baseline of 4 for zero-parameter tools applies here.

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 resonances recorded in the default vault.' It defines the domain term ('A resonance is a workspace that tracks one ongoing project') and distinguishes itself from siblings by pointing to mnemosyne_position_get for full detail and mnemosyne_position_update for writing. This is precise and clearly separates it from related 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 explicitly says there is no status filter, so the tool returns every resonance the scan matched, up to 30 candidates. It also names alternatives for adjacent use cases: 'Read one in full with mnemosyne_position_get, or write a new one with mnemosyne_position_update.' This gives an agent clear guidance on when to use this list tool versus its siblings.

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

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

The readOnlyHint annotation marks this as safe to call, and the description adds behavioral context beyond the annotation: results are newest-first, spine_type restricts only the assignment page while counts remain whole-vault, and include_taxonomy pulls in the global spine tree. No contradiction with the annotations.

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

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

Three sentences with no waste. The core purpose and return shape are front-loaded in sentence one, use cases in sentence two, and the optional taxonomy flag in sentence three. 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?

With no output schema, the description carries the burden of describing return values, which it does: assignments, whole-vault counts, and optionally the taxonomy tree. The readOnly annotation covers the safety profile and the schema documents all parameters, so nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value on top by explaining that spine_type values can be fed back as spine_type_filter into mnemosyne_memory_query, clarifying the cross-tool contract, and by noting the pagination-vs-counts semantic where spine_type scopes the page but not the counts.

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 ('returns') with a precise resource ('memory-to-spine assignments') and clear scope ('one vault, newest first' + 'per-spine counts for the whole vault'). It clearly distinguishes itself from the close sibling mnemosyne_memory_query by stating its output feeds that tool's spine_type_filter parameter rather than querying memories 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?

It gives three concrete use cases: verifying spine placement, reading vault composition, and obtaining taxon ids for use in mnemosyne_memory_query. It references the sibling alternative where the output is consumed. It lacks an explicit 'use X instead when...' exclusion, but the named use cases provide solid routing guidance.

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

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

Annotations only state readOnlyHint=false and destructiveHint=false; the description adds substantial context beyond that: the write is routed through the widget's own store so the user sees exactly what is filed, dev-install headless daemon behavior vs npm installs needing the app running, and the 300/4000 character truncation outcome with an explicit answer note.

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

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

Front-loaded with purpose then the list-naming rule, with the operational caveats (daemon/npm, store routing) placed after the actionable instruction. Dense and mostly waste-free, though the install-mode sentence is somewhat tangential to invoking the tool.

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 mutation tool with no output schema, it covers the full picture an agent needs: required tasks format, list resolution, creation semantics, truncation feedback, and environmental preconditions. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the case-insensitive fallback to the first original list, why create_list defaults to false ('so an agent does not invent lists in someone's backlog without saying so'), and that group maps to a displayed step header. Only the color parameter is left entirely 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?

States a specific verb+resource ('Put tasks into the user's To-do backlog, the To-do widget on their canvas') with scope beyond the name, including ordering and optional steps. It distinguishes itself from the read/update siblings it names explicitly.

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 the trigger condition ('Use it when a conversation has settled what to do'), a concrete list-naming procedure including the LIST_NOT_FOUND discovery call and create_list: true, and routes the agent to mnemosyne_todo_list/_update/_categories for other operations. This is about as complete as guidance gets.

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?

Annotation Contradiction: annotations declare readOnlyHint=true, yet the description describes mutating operations ('create one, rename or recolour one, remove an empty one') and explicitly states 'Scope todo:write'. The title 'List To-do lists' also implies a read-only listing while the description describes workspace mutation. Because the description's semantic content directly contradicts the annotation's safety signal, the score is forced to 1 despite the description itself being behaviorally rich.

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 every sentence carries load-bearing information: operation set, sibling discriminator, two refusal conditions, special status of original lists, runtime requirement, and scope. It is dense rather than bloated, though it reads as one long paragraph — a bullet list of the refusals would aid scannability. No sentence is wasted.

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

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

For a mutating tool with one nested parameter, no output schema, and minimal annotations, the description covers the operations, the sibling alternative, both refusal conditions, the immutable original lists, runtime prerequisites, and required scope. The only substantive gap is the readOnlyHint contradiction, which muddies the reliability of the overall signal; otherwise the description is thorough 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 description coverage is 100%, so the ops array and its fields are already fully documented in the schema (baseline 3). The description adds meaning beyond the schema by explaining refusal behavior at actual call time: the agent is told how many tasks block a removal, must move them first, and the app will not choose a destination on the user's behalf — operational detail the schema lacks. This added value justifies a 4 rather than a 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?

The description opens with a specific verb+resource ('Manage the lists of the user's To-do backlog') and enumerates the exact operation set: create, rename or recolour, remove an empty one. It also distinguishes itself from the most confusable sibling (mnemosyne_todo_update) by naming it directly and explaining the difference: shape of a workspace vs. work in it. An agent can select this tool correctly without opening either schema.

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

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

The sibling routing is explicit: mnemosyne_todo_update is named as the alternative, with the selection rule being whether the change alters workspace shape or work content. The two refusals serve as when-not guidance ('A list that still holds tasks is never removed', 'The three original lists can be renamed, never removed'), and the runtime caveat (daemon on dev install vs. app running on npm install) states a prerequisite condition clearly.

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 provide readOnlyHint=true, so the description is not required to restate that. It adds valuable behavioral context: the difference between dev install (headless daemon reads the file) and npm install (needs app running), and that tasks moved to ARCHIVE are never listed. This goes beyond the annotation and materially affects how an agent plans a call.

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

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

The description is front-loaded with the core purpose and the critical note about IDs, then covers usage and environment context. It is a bit long but every sentence earns its place (the environment note, the scope line, the archive behavior). While it could be tightened, it remains well-structured and readable.

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 read-only nature, optional parameters, and lack of output schema, the description covers all the essential operational details: the return includes IDs needed for updates, the duplicate-check use case, the behavior when no list matches, the archive counting behavior, and the environment prerequisites. Nothing critical is missing 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 the schema already explains all three parameters (list, limit, include_done) in detail, including edge cases like omitted list returning every list and unmatched names returning no tasks. The description adds no additional parameter semantics beyond what the schema provides, so the baseline of 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: 'Read the user's To-do backlog back' and immediately explains what it returns (lists, tasks, and the IDs needed for changes). It explicitly contrasts itself with mnemosyne_todo_update, which names tasks by id, so an agent can distinguish them 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 explicit when-to-use instructions ('Call this before mnemosyne_todo_update') and also positions it as the way to answer 'what is on my plate' or check for duplicates before adding. It mentions the alternative (todo_update) but does not explicitly state when not to use it, so it falls just short of a 5.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses that removal archives by default, that archived tasks can be restored, that the batch is applied in order as one save with per-operation outcome reporting, that a stale id won't sink the rest, and that daemon availability depends on the install type. This is far more transparency than the annotations alone provide.

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?

Every sentence earns its place: purpose, prerequisite, archive behavior, permanent-delete guardrail, batch semantics, failure isolation, environment note, and scope. The most decision-relevant information is front-loaded, and there is no filler or repetition of schema text.

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 complex, has no output schema, and carries a destructive annotation, yet the description covers invocation prerequisites, side effects, ordering, failure behavior, and environment constraints. The only gap is that the exact response shape is not specified, though 'each operation reports its own outcome' provides a useful partial contract.

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 covers 100% of parameters with detailed descriptions, so the baseline is 3. The tool description adds meaningful operation-level semantics: ids come from mnemosyne_todo_list, batch order matters, stale ids are isolated, and permanent deletion requires explicit user intent. This compensates above baseline without duplicating 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 clear verb and resource: 'Change the user's To-do backlog' and then enumerates the concrete operations (edit, complete, move, remove). It also differentiates from sibling tools by requiring task ids from mnemosyne_todo_listable, making the scope unmistakable.

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 and practically important guidance: call mnemosyne_todo_list first, use permanent: true only when the human explicitly asks for outright deletion, and note the environment-dependent daemon behavior. It does not explicitly name an alternative tool such as mnemosyne_todo_add for the 'when not to use' case, so it stops just short of full exclusion guidance.

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

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

Beyond the readOnlyHint annotation, the description adds useful behavioral details: vaults have a local-path `id` that other tools reject, unconfigured vaults are flagged and refused until the user adds them, and the response includes token/display-name/memory-count. This prevents the agent from misusing the wrong identifier.

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?

Every sentence earns its place: it names the resource, tells when to call it, explains how to use the output, warns about the non-useful `id` field, and notes unconfigured-vault behavior. The description is front-loaded and free of 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?

Even without an output schema, the description explains what the response will contain, how to use that response, and the key caveat about unconfigured vaults. For a simple read-only list tool with no parameters, this is complete enough for an agent to call it correctly and act on the results.

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 the description does not need to explain parameter meaning. The baseline of 4 applies here, and the description even adds downstream guidance about how the returned token is used as a parameter in other tools.

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 ('List') and resource ('memory vaults') and states what each listed vault contains: token, display name, and memory count. It clearly distinguishes this tool from sibling list tools like mnemosyne_agent_list or mnemosyne_todo_list by targeting vaults specifically.

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 conditions for use: call it first when unsure which vault to work against, or when the user names a store not yet seen. It also tells the agent how to consume the result by passing the token as the `vault` argument to other tools, and clarifies that the `id` line should not be passed.

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