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

Annotations only declare idempotentHint=false, so the description carries most of the behavioral burden — and it does: 'Nothing in the journal can be edited or deleted afterwards' clearly discloses irreversibility, which is the critical trait for a write tool. It omits size/length constraints and any indication of how entries are later retrieved.

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, zero waste, with the core action and the content guidance front-loaded and the irreversibility caveat immediately after. Nothing to trim.

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 no output schema, the description covers purpose and the irreversible-append semantic well. It would be stronger if it acknowledged the structured 'data'/'tags' dimensions and pointed at journal_read for retrieving past entries.

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

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

Schema coverage is 67% (text and data are described, tags is not), so the schema does most of the work. The description adds no parameter-level information at all — it never mentions the structured 'data' payload or the 'tags' array, so an agent must read the schema to learn that structured detail or categorization is even possible.

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 ('Append one entry to your append-only journal') plus the content scope ('what you did, decided, or learned'). It does not explicitly distinguish itself from the nearby memory_write sibling, which is the main ambiguity an agent would face.

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 phrase 'what you did, decided, or learned' implies when the tool is appropriate, and the append-only framing suggests durable records. However, there is no explicit when-not guidance and no named alternative (e.g., memory_write for mutable notes, journal_read for retrieval), leaving the choice to inference.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's job is lighter. It adds real value with the ordering guarantee ("oldest first") and the session-start framing, but leaves unclear what "most recent" defaults to and says nothing about pagination or entry contents.

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 sentences, no waste, with scope and ordering front-loaded before the usage hint. 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?

The tool is simple and read-only with no output schema, so the description is nearly sufficient. However, with no output schema the agent gets no hint of what a journal entry looks like, and the undocumented `limit` parameter leaves the return volume ambiguous.

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 only 50%: `since` documents its YYYY-MM-DD format, but `limit` has no description or default anywhere. The description could have explained how many entries are returned by default and how limit interacts with the oldest-first ordering, but it does not.

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 your ... journal entries") plus scope and ordering ("most recent", "oldest first"), which no sibling claims. It doesn't explicitly separate itself from memory_read or memory_search, so an agent must infer the journal-vs-memory distinction from the name alone.

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

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

Gives a concrete trigger: "Use at the start of a session to pick up where you left off." That is a clear when-to-use signal, but there is no when-not guidance and no pointer to journal_append or memory_search as alternatives.

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?

destructiveHint=true already flags the safety profile, but the description adds genuinely non-obvious behavior: journal files are immune to deletion, and a paired backup box retains what it already received, so deletion is not fully propagated. It does not state error conditions (missing path, journal rejection) but covers the key 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?

Three short sentences, each with a distinct job: the action, the exception, and the persistence caveat. Front-loaded and zero waste.

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 tool with annotations and no output schema, the description covers scope, exclusions, and the important 'backup keeps a copy' caveat. Only path format and failure behavior are left unaddressed.

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 0% for the single 'path' parameter, and the description never explains its expected format (relative vs absolute, extension, whether it names a directory or file). 'One file' only weakly implies the path targets a file, so the description does not compensate for the coverage gap.

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

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

States a specific verb ('Delete') on a specific resource ('one file from your memory on the box'), and explicitly excludes journal files, which is the main overlap with the journal_* siblings. An agent can tell exactly what this removes.

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?

Usage is implied by the action (remove a stored memory file) and there is a hard exclusion ('Journal files can't be deleted'), but no guidance on when this is preferable to alternatives or on prerequisites such as knowing the path via memory_list/memory_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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the useful scoping detail that listing is confined to "your memory" and may be narrowed by folder prefix, but it says nothing about what is returned (names vs. paths), ordering, or whether listing is recursive under a prefix.

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?

A single front-loaded sentence with no filler; the optional-prefix caveat is attached inline rather than padded into extra sentences.

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-required-param read tool with annotations covering safety, the description is nearly sufficient. The one remaining gap, given no output schema, is that it never says what the listing contains or whether results are recursive.

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

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

Schema coverage is 100% and the schema already documents prefix with an example. The description adds only a second example with a nested path ('projects/keephaven'), which hints at hierarchical prefix matching but doesn't confirm whether matching is recursive or one level deep.

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 in your memory") with the optional scoping dimension. It does not name how it differs from siblings like memory_search or memory_read, so an agent must infer that this enumerates rather than retrieves content.

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?

Usage is implied by the word "List" and the folder-prefix note, but there is no explicit when-to-use guidance and no mention of memory_search as the alternative when the agent wants content rather than filenames.

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 and the description is fully consistent with a safe read. It adds value beyond the annotations by disclosing the return shape (text and etag) and explaining the etag's role in optimistic concurrency for memory_write — behavior an agent would otherwise not know.

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, both earning their place: the action first, then the return value and its downstream use. Zero filler and 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?

With no output schema, the description correctly covers return values and the etag contract, which is the key missing piece for a read tool. Minor gaps remain around non-existent paths and how path namespaces are structured, but the essentials for correct invocation are present.

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?

Single parameter with 100% schema coverage, so the schema's example ('people/dafarus.md') already carries the semantics. The description adds nothing about path resolution, namespaces, or whether paths are relative to a root, so 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 — 'Read one file from your memory' — which distinguishes it from list/status siblings by scoping the operation to a single file. It stops short of naming memory_list or memory_search as the alternative for multi-file retrieval.

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

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

There is one concrete usage hint: pass the returned etag to memory_write to avoid overwriting a newer copy, which implies the read-before-write pattern. However, no guidance is given on when to use this versus memory_list or memory_search, and no error conditions (e.g. missing file) are described.

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?

readOnlyHint=true already declares the safety profile, and the description adds genuinely new context: case-insensitivity and the return shape (matching lines with file and line number). It omits the default value or effect of the 'limit' cap (max 200).

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

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

Two tight sentences with the core behavior front-loaded and the return format second; 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?

A simple two-parameter read-only search with no output schema; the description covers search semantics and the return shape, leaving only the 'limit' behavior unexplained.

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 0%, so the description carries the burden. It clarifies that 'query' is matched case-insensitively as text, which adds meaning, but says nothing about 'limit' or what happens when results are capped.

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: 'Case-insensitive text search across your memory files and journal.' This clearly separates it from memory_read/memory_list, which operate on whole files, though it does not name those siblings 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?

The phrase 'text search across your memory files and journal' implies when to use it (locating content without knowing the file), but there is no explicit when-to-use/when-not guidance and no pointer to memory_read for retrieving full files.

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 already establishes that this is a safe read operation. The description adds useful behavioral context beyond that by disclosing that the tool reports write capability and quota consumption, though it does not detail authentication requirements or exact response fields.

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 concise sentence with no redundant text. It front-loads the main status dimensions the agent would care about.

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, read-only status tool with no output schema, the description covers the key information an agent needs: identity, write permission, and quota usage. It does not specify exact return fields or formatting, but no output schema exists to carry that detail.

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 no parameter semantics burden. The schema is empty and needs no additional explanation.

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 identifies the status report's contents: current identity, write permission, and quota usage. It is more specific than the tool name, though it does not use an explicit verb like 'returns' or 'reports' and does not directly differentiate itself from 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?

Usage is implied by the listed contents: an agent would use this when it needs to know its identity, whether writes are allowed, or remaining quota. However, the description gives no explicit when-to-use guidance, exclusions, or comparison to alternatives like memory_read or memory_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?

Annotations already declare idempotentHint=true and destructiveHint=true, so the safety profile is covered, and 'create or replace' is consistent with it. The description adds real constraints beyond annotations: UTF-8 text, 10 MB cap, and the journal/ write restriction. It does not say whether intermediate directories are created or what the call returns (e.g. an etag for later if_match).

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 short sentences, front-loaded with the action and scope, then size/type limits, then the sibling exclusion. Every clause carries information the agent needs; nothing is redundant with the title.

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 avoids needing to explain return values, and it covers the write scope, size limit, path syntax, and the journal carve-out. The remaining gap is that it never hints at what a successful write returns, which matters because if_match depends on an etag from memory_read.

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

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

Schema coverage is already 100%, so the baseline is 3. The description still earns a bump by specifying path construction rules (allowed characters and '/' separation) that the schema only illustrates with an example. It adds nothing on if_match, which the schema already explains.

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 ('Create or replace one file in your memory') and immediately bounds it to a single file. It also names the sibling it is not (journal_append) and the condition that selects that sibling, so an agent can distinguish it without opening the schema.

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

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

Gives an explicit exclusion with the correct alternative: 'journal/ is not writable here: use journal_append.' That is clear routing guidance, but it only covers the journal case; there is no guidance on when to use memory_write versus memory_delete or on when concurrency control (if_match) matters.

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