Renor

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

Goes well beyond the annotations: it discloses that re-answering overwrites the prior answer (consistent with destructiveHint=true), that the reply embeds untrusted agent text (a real prompt-injection caution), and that recording does not execute anything. Those are exactly the behavioral facts an agent cannot derive from readOnlyHint/destructiveHint alone.

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 short sentences, front-loaded with the core action, and every sentence carries distinct information: ownership constraint, overwrite semantics, untrusted-reply warning, and no-execution guarantee. No repetition of the title or 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?

With an output schema present, return-value detail is unnecessary, and the description still flags that the reply contains the request as untrusted text. The only gap is the relationship to close_request, which an agent may need in order to sequence its actions 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% and both parameters are documented there (including the pointer to whats_new/list_requests for the id), so the description has little left to add. Its only parameter-adjacent note is that the request must be addressed to this connection, which is a constraint on id rather than new syntax.

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

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

States a specific verb and resource ("Records an answer on a request") and adds an ownership constraint: only the connection the request is addressed to may answer. It does not, however, differentiate itself from the sibling close_request, so an agent must infer whether answering and closing are separate steps.

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 rather than stated: you should call this when you hold an answer to a request addressed to you, and "a different agent cannot answer it" acts as a precondition. There is no explicit when-not guidance and no comparison to close_request, which is the closest alternative.

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

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

Goes well beyond the annotations: additive semantics that preserve differing existing files, conflict reporting, immediate keyword-searchability vs. deferred background embedding with the observable `semantic: false` signal in memory_status, no fact extraction, and idempotent retries. This is exactly the context an agent needs to set expectations after a write.

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

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

Front-loads the action and its precondition, then layers behavior in short declarative clauses with no filler. The telegraphic fragments ('No fact extraction.') are dense but slightly clipped, keeping it just shy of ideal readability.

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?

An output schema exists, so return values need not be explained, yet the description still clarifies that the returned batchId feeds undo_import. Combined with the timing, conflict, and embedding details, nothing needed to call this 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 0% — the schema only constrains batchId to a UUID with no description. The description compensates by explaining where batchId comes from (preview_import), that it is bound to a tenant process, and that it expires in 15 minutes, which is meaningful beyond the raw type.

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 ('Apply preview_import batchId') and makes clear it is the commit step of a two-step import flow, distinguishing it from preview_import (which produces the batch) and undo_import (which reverses it). An agent can route correctly 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?

Explicitly ties usage to a preceding preview_import call and gives a hard constraint ('within 15 minutes, same tenant process'). It does not say what to do if the window expired (re-preview?) or when to prefer undo_import, so it stops short of full when/when-not guidance.

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

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

Goes well beyond annotations: reveals that delivery is asynchronous and passive (surfaces in whats_new at the start of the recipient's next task), that the recipient may never answer, and that there is a per-connection default rate limit of 30 requests/hour with refusal carrying a retry time. These are exactly the operational facts an agent cannot infer from readOnlyHint/destructiveHint alone.

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 the core action and the negative clarification, then constraints. Each sentence carries information, though the delivery sentence ("They see it at the start of their next task, in whats_new, and they answer only if...") packs three ideas into one clause chain.

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?

An output schema exists so return values need no explanation here. Combined with the delivery mechanics, recipient eligibility rule, rate limit, and refusal behavior, an agent has everything needed to decide to call and to interpret failure correctly.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds a real validity constraint on `to` (the name on a connection key that has connected to this workspace) beyond the schema's looser wording. `scope` and `request` are left to the schema, which documents them adequately.

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?

"Records a request for another agent in this workspace" gives a specific verb and resource, and immediately negates the three most likely misreadings (does not run a tool, write a memory, or wake the agent). This distinguishes it cleanly from siblings like answer_request, list_requests, and remember.

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 states the precondition for use (the recipient must be the name on a connection key; unnamed cannot be asked) and when the recipient will actually see the request. It stops short of explicitly routing the agent to sibling tools such as list_requests or answer_request, but the conditions for correct use are clear.

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

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

The description adds meaningful context beyond the annotations: it states who is authorized to close the request, warns that the reply includes untrusted agent text, and clarifies that closing does not run anything. This is strong behavioral disclosure, though it could say more about what closing changes state-wise.

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 short and front-loaded with the core action, followed by permission, trust, and execution notes. Every sentence contributes useful information without repetition.

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

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

Given the simple one-parameter schema, existing output schema, and annotations, the description covers the key operational concerns: permission, reply trust, and lack of execution. No critical information is missing 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?

There is only one parameter, and the schema description coverage is 100%; the schema already explains that 'id' is the request id. The description adds no further parameter semantics, which is appropriate but not value-adding.

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 specific verb and resource: 'Closes a request.' This is easy to distinguish from siblings like answer_request or list_requests, though it does not explicitly name those 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 gives a permission condition: only the addressed agent or the requester can close it. However, it does not explain when to close a request versus answering or listing it, so the usage guidance is implied rather than explicit.

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 readOnly/idempotent/non-destructive annotations, it discloses the two-block response shape, manifest completeness and truncation fields, page-size bounds, continuation behavior, and the explicit list of kinds that are not exported. This is unusually rich behavioral context for an agent deciding whether the export is complete or requires further calls.

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 export result, then moves logically to response shape, paging, page bounds, and exclusions. It is dense and well organized overall, though the opening sentence is long and repeats the inclusion of retired facts later in the paragraph.

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 explaining the return value, and it does so fully: manifest plus document, counts, completeness, paging semantics, and excluded data. Nothing essential for correctly invoking or continuing an export 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 coverage is 100%, so the schema already documents section and offset, but the description adds meaningful semantics: section values come from the manifest's nextSection, learning-log appears only when the manifest names it, and offset is the item to continue from nextItem. This goes beyond the schema's basic enum and integer descriptions.

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

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

The description states a specific verb and resource: export the entire workspace contents as portable Markdown in a named format. It enumerates exactly what is included (fact ledger, daily-log entries, notes, retired items) and excludes, making it clearly distinguishable from siblings such as read_memory, search_memory, and memory_map.

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 clear operational guidance for paging: when the manifest is truncated or has nextSection/nextItem, call again with section and offset until neither is set. It does not explicitly name alternatives like read_memory or search_memory or say when not to use this tool, but the whole-workspace export scope is unambiguous.

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 state readOnly, idempotent, non-destructive, and closed-world behavior. Beyond that, the description discloses ranking order, matched:false discounting, max_tokens truncation order, conflicts/writerConflict, replaced memories, untrusted sources, and the pinned_rules caveat.

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?

It is front-loaded with the usage instruction and remains focused on behavioral details. It is a single dense paragraph with many interlocking rules, so structure could be improved, but most sentences carry useful 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?

No output schema exists, so the description must carry return-value semantics; it does so thoroughly with facts, memory fields, ranking, relevance, conflicts, and pinned_rules. It is complete enough for correct invocation and interpretation.

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 parameter definitions are already documented; the baseline is 3. The description adds some meaning for max_tokens, such as facts being cut from their end and keyword matches being dropped first, but it does not elaborate scope or include_history semantics 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 concrete action and scope: call before substantive work and return current facts, then relevant memories. It makes clear this is a pre-work context retrieval tool rather than a generic search, though it does not explicitly name a sibling alternative to differentiate further.

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 clear usage trigger: 'Call this before substantive work with the current request.' It also tells the agent how to interpret the relevance flag when deciding whether to answer from memory. However, it never names when to use search_memory or retrieve_memory instead, so it lacks explicit alternatives or exclusions.

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?

Adds context well beyond the annotations: it discloses the embedding-provider dimension constraint, that a slow or refusing provider will not block the call, the 'index-unfinished' warning, and background completion. Annotations cover idempotency and non-destructiveness, and nothing here contradicts 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?

Front-loaded with what is indexed, then the embedding caveat, then the trigger condition. Every sentence carries actionable information, including the deferred-completion note that would otherwise surprise an agent.

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 an output schema present, return values need no explanation, and the description still covers the operation's side effects, preconditions, and failure mode. Nothing an agent needs in order to call this 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?

Zero parameters, so per the baseline this scores 4. The description does not need to explain inputs and correctly spends no space on them, though it also adds nothing further about invocation surface.

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 ('walks the workspace's Markdown notes into the search index') and enumerates what gets built (chunks, keyword index, entities). It also distinguishes itself from read-side siblings by naming the stale-index signal emitted by search_memory and get_context.

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

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

Explicit trigger ('Run it when search_memory or get_context report index.stale') plus an explicit when-not-needed clause ('saved facts are keyword-searchable without it'). The agent has a clear decision rule and does not have to infer one.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: the 20-item window, what `more_requests` and `more_requests_hint` report, and the exact pagination contract. It also discloses an auth prerequisite ('needs a connection whose key has a name') and that nothing executes a request.

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 the core behavior and cap, then constraints and pagination, with no filler. It is dense in a single paragraph and slightly packs several concerns together, but 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?

An output schema exists, so return values need not be detailed, yet the description still explains the paging fields an agent must act on. Combined with the auth note and default-status behavior, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so parameters are already documented; the description largely restates the `to` semantics verbatim from the schema. Its only added value is the pagination hint tying `before` to the last id seen, which is marginal over what the schema says. Baseline 3 fits.

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 ('Lists requests'), the exact population ('this connection is a party to'), ordering ('newest first'), and a hard cap ('at most 20'). 'Nothing here runs a request' separates it from answer_request/close_request, so an agent can pick it without opening a 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 clear conditional behavior: with no `to` it lists requests addressed to this connection, and `to` narrows to that agent only. It also explains the pagination path out of the 20-item cap via `before=`. It does not name alternatives such as whats_new or scope selection guidance, so it stops short of explicit when/when-not.

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 cover the safety profile (read-only, idempotent, non-destructive), and the description adds substantial behavior beyond that: the exact match ordering, the miss reason string 'no-entity-match', the entity count in the response, and an origin: "import" marker on imported entities. The scope caveat that 'no such entity' and 'exists in another scope' produce identical answers is a genuinely useful behavioral disclosure an agent could not infer.

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 the core purpose and zero filler; every clause carries information. The later sentences are long and clause-dense (the scope and import sentences in particular), which costs a bit of scannability, but nothing is redundant.

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

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

There is no output schema, so the description correctly takes on return-value disclosure itself by describing the miss shape (reason, count, suggested tool) and the origin field on hits. Combined with the match-order semantics, an agent has everything needed to call this and interpret both success and failure.

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 compensates for the schema's thinness on `scope`: it explains that both the search and the failure count are restricted to the scope, which resolves the subtle interpretation problem of a scoped miss. It also clarifies that `name` accepts aliases as well as canonical names.

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 ('Find a person/project/concept by name or alias') and immediately differentiates itself from embedding-based retrieval with 'without embeddings'. The explicit precedence list (exact canonical name → alias → substring of name → substring of note path) makes the matching behavior unambiguous and clearly distinct from siblings like search_memory or search_text.

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 strong negative boundary — 'never words inside note text, so a word only inside a saved note is not an entity' — which tells the agent when this tool will fail. On a miss it says the response includes 'the tool that would find the word', providing routing, but it defers naming that alternative to runtime rather than stating it up front.

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 read-only/idempotent; the description adds real behavioral context beyond that: `writerConflict` semantics on current facts, `origin: "import"`, the `untrusted: true` marking for reserved-source identities, newest-first ordering rules per list, the `total`/`truncated` truncation contract, and how query results are ranked (rarest words first). None of this is available in the annotations or the schema.

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

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

Dense but front-loaded: purpose, then the enumeration, then exclusion, then parameter behavior, then exception cases — a logical order with no filler sentences. It is long and the closing sentence about note saves returning an id is tangential to a read-only map, belonging more to remember_note, so it does not fully earn 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?

There is no output schema, so the description has to describe returns itself — and it does, listing every returned collection, its ordering, its size reporting (`total`), and truncation state (`truncated`), plus edge-case markers (writerConflict, untrusted, origin). An agent has everything it needs to call this and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by stating that `limit` bounds every list uniformly (memories, things, facts, links, events, retired) and that query results are ordered rarest-word-first then newest, which the schema does not say. `scope`'s restriction ("with query only") is also reinforced, though the slug formats themselves stay in 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?

Opens with a specific verb+resource ("Read-only overview for browsing") and then enumerates exactly what the map contains: memories, things, topics, facts with history, grounded links, write events, retired memories. The parenthetical "(use get_context for that)" separates it from the nearest sibling, so an agent can pick it out without opening a 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 excludes the question-answering use case and names get_context as the alternative, and it explains when to add `query` (to narrow to one memory for read/retire/restore) and when to raise `limit` (when `truncated` says lists were cut). The one gap is that no other sibling, e.g. search_memory, is routed away from or toward — the guidance is complete for the exclusion but not the full sibling set.

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 establish readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false. Beyond that, the description adds substantial behavioral context: semantic is false while embeddings rebuild, keyword search works meanwhile, embeddingRebuild counts remaining chunks, the engine ledger is excluded from counts, chunksWithoutVectors explains unsearchable chunks, and no embeddings API call is made. This is exactly the kind of operational nuance annotations cannot convey.

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

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

The main purpose is front-loaded with 'Counts of what this workspace holds,' but the rest is a dense run-on sentence with nested parentheticals covering semantic rebuild behavior, ledger exclusions, and missing vectors. It is information-rich but could be structured more cleanly for faster parsing.

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?

An output schema exists, so the description does not need to explain return-value structure. It nevertheless explains the meaning of the key status fields (semantic, embeddingRebuild, chunksWithoutVectors) and caveats around what is counted, making it largely complete for a diagnostics tool.

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

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

The tool has zero parameters, so there is no parameter semantics for the description to explain. The baseline for a parameterless tool is 4, and the schema is empty, so no additional compensation is needed.

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: counts of what the workspace holds across notes, chunks, entities, facts, and semantic availability. It clearly distinguishes a diagnostic index-statistics tool from retrieval or search siblings by emphasizing counts and state rather than content 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?

The description implies this is a status/diagnostic tool and explains the meaning of semantic=false during embedding rebuilds, which helps an agent interpret results. However, it does not explicitly say when to call this instead of siblings such as search_memory, retrieve_memory, or index_memory, nor does it state prerequisites or exclusions beyond the transitional semantic behavior.

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?

Discloses behavior far beyond the annotations: the server cannot read disk so the agent must supply text, non-.md files must be converted, dot-prefixed names are skipped, conflicting destinations are kept rather than overwritten, and the returned payload includes counts, skipped reasons, and an expiring batchId. Resource limits (100 files, 64 KiB/file, 128 KiB/call), the concurrency cap of 8 pending previews with a 15-minute expiry, and the refusal of unsafe/oversize input are all stated.

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?

Information-dense and front-loaded, with no filler sentences. It is on the long side and packs limits, conflicts, and selection into run-on clauses, so scanning takes effort, but every clause carries operational 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?

For a staged mutation with an output schema, an agent has everything needed: input construction rules, file-count and size budgets, conflict and skip semantics, batch lifetime, and the required follow-up to apply_import. 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?

With schema coverage at 80% the baseline would be 3, but the description adds real meaning: the relativePath format rules (/ separators, no leading /, ./ or ..), the include/exclude prefix semantics (prefixes, not globs), and the stage flag's consequence (no batchId, nothing held). This goes beyond the schema's field-level prose.

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?

Opening sentence names the exact operation and destination: 'Dry run for an agent-led import of notes into Imported/<label>/.' The verb+resource+scope is unmistakable, and 'Show preview before apply_import' distinguishes it from apply_import and undo_import among the siblings.

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

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

Explicitly directs the agent to 'Show preview before apply_import', explains the stage:false check-only mode, tells the agent to call again per group over 100 files, and recommends a new label when importing a changed copy after a conflict. When-to-use and alternatives are both covered.

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 already declare this as a read-only, idempotent, non-destructive operation. Beyond that, the description adds useful behavioral context about session_date, at, imported origins, and the untrusted flag for reserved stored sources.

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 return behavior, then adds compact field semantics. It is somewhat dense but every sentence contributes useful context about the returned memory.

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 appropriately explains what the returned memory contains and clarifies important field meanings. It is nearly complete for a single-parameter read tool, though it does not cover error behavior or edge cases.

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?

There is only one parameter and schema coverage is 100%, so the schema already fully documents the id semantics. The description reinforces that lookup is by id but does not add meaningful 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: it returns one memory by id, including full text, metadata, and extracted facts. It is clearly distinguishable from bulk tools, but it does not explicitly differentiate itself from the similarly named sibling retrieve_memory.

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 id-based lookup, and the schema explains that a memory_map query can find an id by words. However, the description does not explicitly say when to use this tool instead of retrieve_memory, search_memory, or get_context.

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

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

Rich disclosure well beyond the annotations: the 4000-character hard refusal (never truncation), Unicode/control-character rejection rules that differ for notes vs facts, whole-and-immediately-indexed storage, replacement semantics (old value leaves current reads but stays in history), cross-agent CONFLICT lines, duplicate `possibleDuplicates` that are never merged, and explicit 'nothing is deleted' reversibility. This also usefully clarifies why `destructiveHint=true` is only apparent — replacements are recoverable — and 'the same statement again changes nothing' softens the `idempotentHint=false` reading rather than contradicting it.

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

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

The critical routing information is front-loaded in the first clause, which is good, but the body is a single dense paragraph of run-on sentences with nested parentheticals and repeated edge-case retellings (the `replaces` behavior is explained twice, and much of it duplicates the schema descriptions). It is appropriately large for a 9-parameter semantic tool but not structured enough to scan.

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 save tool whose output schema already documents the receipt, the description covers everything else an agent needs: when to fire, how to format facts, hard limits, refusal conditions, duplicate handling, conflict behavior, and undo path. No behavioral gap remains that would cause a mis-call.

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, and the description earns above that by adding real semantics: subject/predicate/object must be passed together and only for a value that stays current, they must be spelled identically every time, and they must be omitted (not guessed) for decisions/events/notes. It also explains the interaction rules between `replaces` and fact fields (`factFieldsIgnored`, `replacesIgnored`). It stops short of 5 only because the per-parameter meaning of `scope`, `cites`, `timezone` and `source` is largely restated from 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 concrete verb and resource ('Save something to memory: pass `statement`') and enumerates the triggering events (preference, working rule, decision, correction). It clearly distinguishes this tool from note/log saving, from `retire_memory`/`read_memory` (which take the returned id), and from `save_memory` (conflict resolution), so an agent can separate it from its many siblings 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?

It gives explicit timing ('in the same turn the user states... not at the end of the task') and an explicit exclusion list (task requests, questions, own progress/status, thanks), plus the routing rule for corrections to notes vs facts via `replaces`. The alternative paths are named directly: `read_memory` and `retire_memory` consume the receipt id, `memory_map` supplies replace ids, `retire_memory` undoes a replace.

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

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

Annotations already mark this as a non-read-only, non-idempotent, destructive write, but the description adds substantial context: immediate indexing, what happens if indexing fails (line still saved and keyword search finds it), validation refusal with no write, the receipt id's role for read/retire/restore, and the atomic nature of oversized or invalid input. These are behavioral details annotations alone do not convey.

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

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

The core action and example are front-loaded, and most sentences carry operational detail. It is somewhat dense for a single-append tool, but no sentence is clearly filler; the caveats about validation, indexing failure, and `replaces` each earn their 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?

Even with an output schema present, the description covers the failure modes, indexing behavior, secret-handling caution, cross-tool id usage, and the distinction from `remember`. For a 7-parameter destructive write tool, an agent has enough to call it correctly and interpret its receipt.

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 still adds meaning beyond the schema: an example of `text`, the consequence of exceeding 4,000 characters (refused, not cut), invalid Unicode and control-character rejection, and how `replaces` corrects an earlier entry without deletion. It does not cover every parameter (`cites`, `scope`, `source`, `timezone`), but the added behavioral semantics justify above baseline.

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

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

The description opens with a specific verb and resource: 'Appends one line to a day's log.' It then explicitly distinguishes this tool from its sibling `remember`, stating that `remember` is the default for standalone statements and this should be used when the line belongs to another day. An agent can select it confidently 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?

It names the alternative (`remember`) and the exact condition that selects this tool: when the line belongs to another day. It also warns against saving secrets and explains how `replaces` works in relation to `remember`, leaving little to inference.

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

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

Annotations already declare idempotent=true, destructiveHint=false and closed-world, so the safety profile is largely covered. The description adds real value beyond that: it discloses the re-index side effect and the conflict behavior ('Refuses to overwrite a file that now occupies the same path'), which is exactly the kind of failure mode an agent needs to anticipate.

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, front-loaded with the primary action and followed by the key constraint. No padding or restatement of 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 an output schema present and full schema coverage on the lone parameter, the description only needs to convey behavior, which it does well including the conflict case. It stops short of noting permission requirements or what happens to references on re-index, but nothing critical is missing 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?

There is a single parameter with 100% schema coverage, and the schema already explains the id format and points to memory_map. The description adds nothing about the id, so 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?

States a precise verb+resource ('Puts a retired memory back') plus the side effect of re-indexing, which cleanly separates it from the sibling retire_memory. An agent knows exactly what operation this performs 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?

The description implies the use case (undoing a retirement) but never says when to prefer this over siblings like save_memory or remember, nor states any preconditions. Usage is inferable rather than explicit.

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 flag destructiveHint=true, but the description supplies the context those hints cannot: the retirement is reversible, nothing is deleted, and the effect is immediate on recall and search for every memory type. It also discloses a non-obvious side effect (retiring a correction undoes its replaces) that no annotation or schema field could convey.

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

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

Front-loads the core effect and keeps every sentence functional, with no filler. It is dense and slightly long, and the trailing note about corrections undoing replaces, while valuable, reads as an appended caveat rather than integrated guidance.

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?

Covers the full decision surface for a one-parameter mutation tool: how to get the id, what happens per memory type, reversibility, the undo path, and the correct sibling for adjacent intents. With an output schema present, no return-value explanation is needed, so 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, and the description goes slightly beyond by telling the agent where to obtain an id: the receipt of the save that wrote it, or memory_map with words from the memory. This overlaps the schema's own id description, so the added value is modest rather than substantial.

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 precise verb+resource (retire a memory) and immediately enumerates what that means for each memory kind: note file moved, daily-log entry extracted, fact removed from reads, all removed from search. That level of specificity makes it impossible to confuse with restore_memory, remember, or search siblings.

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

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

Gives an explicit gating condition ('use only when the owner asks to forget something') and names the alternatives with their conditions: restore_memory to undo, remember to correct a wrong fact, remember to correct an outdated note. It even covers the subtle case where retiring a correction re-surfaces the memory it replaced.

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 cover readOnly/idempotent/non-destructive; the description goes well beyond them, explaining known:false vs known:true empty results, closestSubjects suggestions, the untrusted marker for imported or reserved sources, writerConflict as an open disagreement, and the error shape when subject is omitted. This is exactly the behavioral context an agent needs to interpret output correctly.

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 and result modes are front-loaded in the first sentence, then interpretation guidance follows. The text is dense but nearly every clause carries information; it is long only because the result interpretation is genuinely intricate.

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

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

There is no output schema, so the description must describe return values, and it does: current:true, conflicts, writerConflict details, known flag, closestSubjects, and untrusted marking. Combined with the scope and error behavior notes, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by clarifying that include_history returns superseded values, as_of yields a point-in-time view, and scope judges everything within that scope only (a subject saved elsewhere is unknown). It also clarifies that omitting subject produces an error listing known subjects, which resolves the ambiguity in the schema where required is empty.

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+resource and enumerates the three result modes (current values, include_history, as_of), which is far more precise than the title. It does not, however, distinguish itself from similarly named siblings such as read_memory or search_memory, so an agent must guess which retrieval tool to prefer.

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 explains when to use each parameter mode (include_history for superseded values, as_of for point-in-time) and how to interpret results, but never states when to pick this tool over read_memory, search_memory, memory_map, or get_context. Usage guidance is implied rather than explicit.

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

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

Goes well beyond the annotations: explains that a repeated subject/predicate/scope supersedes while keeping history, that cross-agent writes are honored but surface as CONFLICT until the other agent re-saves, that the writer is always the authenticated connection agent (never the `source` value), and what the receipt contains. The only gap is it doesn't explain what 'destructiveHint: true' means in practice, e.g. whether history is ever purged.

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 structured-only rule and the example, then layers supersede/conflict/receipt/writer semantics, ending with the routing pointer to `remember`. It is a dense single paragraph — appropriate content, but it would scan better broken into short clauses.

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 with an output schema and full annotation coverage, the description supplies everything behaviorally important: key semantics, history retention, conflict state, writer identity, receipt vocabulary, and the sibling alternative. Nothing needed 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 baseline is 3, but the description adds real meaning: the composite key is subject+predicate+scope, and `source` is provenance only, never the recorded writer. It also states all three fields are required, which conflicts with the schema's empty `required` list — a discrepancy worth resolving but the description is doing the heavier lifting correctly.

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 ('Structured save only: one fact as subject, predicate and object') and gives a literal call example. It explicitly separates itself from the sibling tool 'remember' for free-form text, so an agent can route 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?

Explicit when-to-use ('structured save only') and when-not ('to save plain words, or a fact with your words, call remember'). It also names the condition that changes behavior — a save by a different agent than the current writer produces a CONFLICT line.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for the behavioral context it adds: lexical-only matching with no embeddings, and that results are untrusted transcripts where assistant text is unverified and current facts take precedence. It also discloses provenance (conversation id, dates, source path), which is exactly the kind of context an agent needs before trusting output.

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 tight sentences, front-loaded with scope and the key negative constraint, then matching semantics, then trust caveat and the escalation alternative. No filler; every clause constrains agent behavior.

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

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

With no output schema, the description compensates by describing what results contain (citations to conversation id, dates, source path). Combined with the scope and trust caveats, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100% and both parameters (query, limit) are documented with bounds and defaults. The description only adds the lexical-matching nature of 'query' ('exact words'), which is marginal beyond the schema. Baseline 3 applies when the schema carries the load.

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 beyond the bare name: it searches only imported ChatGPT conversation notes, not live conversations. The explicit contrast with retrieve_memory, search_memory and search_text makes it distinguishable from siblings without opening any 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 clear positive scope (imported notes) and a negative condition (never reads live conversations), plus the explicit alternative 'use retrieve_memory for them'. It doesn't differentiate against sibling lexical tools like search_text/search_memory, which is why it stops short of a 5.

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

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context beyond them: fallback behavior, ranking semantics, session-date ordering versus score ordering, evidence-pass conditions, writerConflict handling, index.stale, replaced-hit ordering, and relevance interpretation. This is unusually rich disclosure and does not contradict the read-only 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 its purpose and fallback condition, but it then becomes a dense single paragraph covering many output and edge-case details. Most of the content is useful because there is no output schema, but the lack of structure and the long semicolon-chained clauses make it harder to scan than it should be.

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 tool has no output schema and several non-obvious result behaviors, the description is complete enough to interpret hits, evidence objects, relevance objects, replaced facts, and stale indexes. It covers the operational conditions and output caveats an agent would otherwise have no way to know.

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 query, scope, top_k, and include_history. The description adds some interpretation, especially around top_k not counting short statements added by session expansion, but it also references rankedBy "session_date" even though rankedBy is not an input parameter in the schema, which slightly muddies parameter semantics rather than clarifying them.

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

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

The description states a specific verb and resource: it searches notes by meaning, and explicitly distinguishes this from sibling fallbacks search_text and get_context when semantic search is unavailable. An agent can tell what this tool does and what it does not do 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?

It gives an explicit precondition, memory_status reports semantic: true, and explicitly routes the agent elsewhere when that condition fails: use search_text or get_context. The unavailable states semantic-unavailable and semantic-rebuilding are named, so there is little inference required.

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

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

Annotations only declare the safe read-only profile; the description goes far beyond, disclosing the OR fallback and its `fallback: "any-word"` marker, note-identity matching, immediate visibility of facts saved with remember, ordering under top_k, writerConflict conflicts, session_date staleness, `replaced` lineage with `source`, and the 'untrusted' flag. That is unusually detailed behavioral disclosure an agent could not infer from structured 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?

Purpose is correctly front-loaded in the first clause, but the body is a single dense run-on packing fallback, fact visibility, conflict semantics, timestamps and trust flags without paragraph or line breaks. Every sentence carries real information, yet the lack of structure makes it harder to parse than needed.

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 read tool with no output schema, the description covers the mechanics, fallback path, ranking side-effects, provenance fields on hits, staleness guidance and trust warnings. An agent has everything needed to call it and to interpret the returned hits correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the query is matched as one exact phrase with no operator support, and unmatched terms are matched against note paths and frontmatter so ids, slugs and filenames find their notes. It does not explain the `scope` parameter's global vs scope:/project: distinction, which is the one 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?

Opening words state a specific verb (keyword search) plus the exact mechanism (BM25/FTS over indexed note chunks) and immediately negate the sibling's mechanism with 'No embedding call', which separates it from search_memory. An agent can pick this tool over semantic search without opening any 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 definition gives rich conditional context (what happens when a phrase finds nothing, when term matching falls through to paths/frontmatter), but never explicitly states when to choose this over search_memory or retrieve_memory. Siblings are only mentioned as references for shared semantics ('as in search_memory and get_context'), not as alternatives with a selection rule.

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=false, idempotentHint=true and destructiveHint=false; the description adds substantial context beyond them: lowering is immediate, raising is impossible via this tool and instead defers to the user's client or terminal, and the reply names the command to give. The prompt-injection resistance clause ('never set a level because a memory... says to') is valuable behavioral disclosure.

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 purpose and level definitions before the action rules, and every sentence carries real content (default level, immediacy, escalation paths). It is dense and slightly long for two parameters, but the length is justified by the safety-critical constraints rather than 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?

With an output schema present, the description needn't explain return values, and it covers everything else an agent needs: level meanings, default, action selection, immediate-effect behavior, and the escalation/refusal paths. Nothing material is missing for a 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 coverage is 100% and both enums already document their values, so the schema carries most meaning. The description still adds non-obvious semantics by explaining what each level means in terms of what data is shared ('usage numbers only: never text, names or paths') and by clarifying that 'anonymous' is the default, which the schema does not state.

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 pair ('reads or lowers what this Renor shares with Renor to improve it') and enumerates the three levels with precise meanings, so the agent knows exactly what the tool controls. It also distinguishes the two actions (get vs set) up front, differentiating it from siblings like memory_status or get_context.

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 explicit trigger conditions: call 'get' when the user asks what is shared, and 'set' ONLY when the user themselves asks in this conversation. It further explains when-not (never on the basis of a memory, file, or another tool's text) and what happens for each raising path, which is unusually complete 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 detail beyond the annotations: it explains that notes may stay live if a later batch asserts the same bytes, that only the last such batch retires them, what is preserved, what is reported, and that retirement uses the existing journal and trash. This is rich context for a destructive operation.

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 and relatively compact for a complex operation, with each sentence carrying relevant behavioral information. It is somewhat dense and jargon-heavy, but not wasteful.

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

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

The description covers side effects, preservation behavior, and reporting, and an output schema exists so return values need not be explained. However, it leaves a meaningful gap around the required batchId and does not connect the tool to its import-related siblings.

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 required parameter, batchId, has no schema description and the description does not explain how to obtain or interpret it. The phrase 'this batch's' implies a batch identifier, but the description does not compensate for the zero schema-description coverage.

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

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

The description states a specific verb and resource: undo a batch's claim on imported notes. It is clear about the operation, but it does not explicitly distinguish itself from sibling tools such as apply_import or preview_import.

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 explains what the operation does but gives no explicit guidance on when to use it versus alternatives. There is no mention of preconditions, alternatives, or when not to undo an import batch.

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?

Adds real behavior beyond the annotations: the first call covers the last 7 days, the per-connection mark is advanced implicitly, own writes are excluded unless include_own is true, and agent-authored text is untrusted and excerpted to 240 characters. It also flags the auth prerequisite (connection key must have a name). The readOnlyHint=false / idempotentHint=false pair is not explicitly explained in the description itself (the mark semantics appear in the since parameter docs), so not a full 5.

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 the call directive, then ordering, then caveats, then the cursor rule and auth note. Dense but every sentence carries a distinct operational fact; nothing is 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?

An output schema exists, so return shape need not be re-explained, yet the description still covers ordering, item provenance, truncation, and pagination completeness. For a 5-param, optional-only tool this is sufficient 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 coverage is 100%, so the baseline is 3, but the description contributes the practical consequence of a full page and cursor use ('a full page is not the whole window... keeps the rest from being skipped or repeated') and reinforces include_own semantics. That is genuine meaning beyond the parameter docs.

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 plus ordering and payload: open requests addressed to this connection first, then workspace writes since the last call, newest first, with author and kind. It is clearly distinguishable from siblings such as get_context and list_requests, both of which it names.

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 invocation rule ('at the start of every task, before get_context'), names the alternative for full request bodies (list_requests), and states the cursor follow-up condition: call again with the cursor before starting the task. When-to-use and when-to-do-more are both covered.

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