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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description earns credit for details annotations cannot express: config file contents are returned with secrets redacted, and it never emits secrets or API keys — the key behavioral concern for a tool that dumps configuration. It slightly restates read-only, but the redaction guarantee is genuinely additive.

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 purpose sentence, then a scannable bullet list of what is returned, then a use-case line. Every element earns its place except the trailing 'Read-only', which merely echoes readOnlyHint=true already in the 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 no output schema, the description carries the burden of describing returns and does so by enumerating the diagnostic sections. It stops short of indicating the response shape (structured object vs. formatted text) or approximate payload size, which is a minor gap for a config-dumping 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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. It correctly signals a no-argument invocation by omission, and 'additionalProperties: false' in the schema confirms no inputs are accepted.

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?

Specific verb-and-resource pairing: 'Return version, system, and configuration diagnostics for Basic Memory', followed by an explicit enumeration of the payload (package version, Python/platform, config path and contents, BASIC_MEMORY_* env vars). No sibling tool in the list is a diagnostics tool, so it is unambiguously distinguishable from the note/project/schema 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?

Names a concrete use case — 'troubleshooting installations and gathering information for support requests' — which tells the agent when to reach for it. It does not state exclusions or name an alternative, but no sibling overlaps with this behavior, so the omission is low-risk.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real value beyond them: what `compact` strips, that `depth` bounds traversal at 5 hops, and that `since` narrows related results. It does not discuss pagination behavior across primary vs related results, which is left to 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?

Four tight sentences: traversal scope first, then the identifier contract, then the time filter, then the compact/read split. Every sentence carries operative information and none repeats the tool title back at the reader.

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 described. Required input is a single identifier, which is fully specified, and the highest-leverage optional knobs (depth, since, compact) are explained. The remaining params are low-risk tuning values documented in the schema at 89% coverage.

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 89%, so the baseline is 3; the description goes further by enumerating the identifier formats (path, permalink, memory:// URL, glob pattern), clarifying that `since` applies to related results rather than the root note, and explaining the practical consequence of `compact`. Page, page_size, max_related and project are left to the schema, which is acceptable at this 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?

States a specific verb and resource: follow the Basic Memory knowledge graph from a note, returning the note, its observations, and notes reached by relations up to `depth` hops. It also distinguishes itself from bm_read by naming that sibling as the way to read full note bodies, so an agent can tell the two apart 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?

It gives clear context for use (graph traversal from a starting note, with `compact` for a body-free view) and explicitly routes follow-up reading to bm_read. It does not state when NOT to use this versus search_notes or bm_search, so it falls short of a full when/when-not/alternative treatment.

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 destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description still adds real value: irreversibility, the cascading scope of a directory delete, and the error behavior for a missing note. It stops short of noting permission requirements or what the response reports after deletion.

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, each carrying a distinct rule — target selection, recursive requirement, concurrency guard, error case, and irreversibility. No filler and the destructive warning lands at the end where it is read.

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, and the description covers both deletion modes, the safety precondition, and failure semantics. Only the project-scoping parameter and post-delete response behavior are left entirely to structured fields.

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 83%, so the schema already documents most parameters. The description reinforces the identifier/path split and the checksum's provenance from bm_read, but says nothing about `project` or `output_format`, so it only marginally exceeds the baseline.

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

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

Specific verb plus two clearly delineated resources: a note via `identifier` or a directory via `path`. The description makes the two deletion modes and their parameter mapping explicit, which distinguishes it from read/edit 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 concrete conditional rules: `recursive=true` is required for directories, and `expected_checksum` (sourced from bm_read) guards against concurrent modification. It does not name or rule out alternatives such as the sibling `delete_note`, so routing 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?

Annotations already mark this as destructive, non-read-only, and non-idempotent. The description adds useful behavior beyond those hints: optimistic concurrency via expected_checksum, exact replacement-count enforcement, missing-note errors, and metadata merging without touching the body. It does not call out that replace_section may remove subsections by default, though the schema documents that.

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

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

The description is dense but front-loaded and appropriate for a seven-command editing tool. Every sentence adds operational detail, and the command mapping is organized efficiently despite the compact paragraph form.

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 rich schema, output schema, and annotations, the description covers the critical editing semantics and error behavior. Minor gaps remain around explicitly warning about replace_subsections' destructive default and fully differentiating from the edit_note sibling.

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 high, but the description adds cross-parameter meaning that is not obvious from individual field descriptions: how command selects content, find_text, section, metadata, and expected_checksum behavior, including that metadata merges with any command and expected_checksum comes from bm_read.

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 gives a specific verb, resource, and scope: changing part of an existing Basic Memory note. It also distinguishes creation by directing missing notes to bm_write, but it does not explicitly differentiate itself from the sibling edit_note tool.

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 clearly states that missing notes are errors and should be created with bm_write, and it references bm_read for checksums and section syntax. It does not give an explicit when-not rule against using sibling tools such as edit_note.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds useful operational context: recursive search, path scoping, frontmatter filtering, and projecting selected fields, though it does not restate pagination behavior or the `fields`-requires-`filters` constraint that appears in the schema.

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

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

The description is front-loaded with the core purpose and then efficiently covers the main modes and the alternative tool. Every sentence earns its place, with no filler or repeated annotation metadata.

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 nine-parameter read-only search tool with a rich input schema, an output schema, and strong annotations, the description covers the essential selection and invocation context. It leaves pagination and some parameter interactions to the schema, which is acceptable given the 89% coverage but prevents a perfect score.

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 89%, so the schema already documents most parameters thoroughly, including the detailed `filters` operator grammar. The description reinforces `name`, `filters`, `fields`, and `path` with examples but does not add significant meaning beyond the schema, so the high-coverage baseline of 3 is appropriate.

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

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

States a specific verb and resource: find files in a Basic Memory project, recursively. It clearly distinguishes its modes (`name` glob, `filters` frontmatter matching, `fields` projection) and explicitly routes ranked text/meaning search to `bm_search`, so an agent can tell it apart from that sibling 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?

Gives clear usage context for each major mode and names the alternative for ranked text or meaning search: use `bm_search`. It does not explicitly state the `name`/`filters` mutual exclusion in prose, although the schema does, so it falls short of fully explicit 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond that: ordering guarantees ('subfolders, then its files'), the fields returned per file, and cross-project addressing. It does not mention pagination behavior, which is the one notable gap.

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 tight sentences, front-loaded with the core behavior, then addressing rules, then the sibling redirect. No filler and no repetition of schema text.

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

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

With 7 optional parameters, rich annotations and an output schema, the description covers the essentials an agent needs to pick and call this tool. The only missing piece is that results are paginated (page/page_size defaults), which an agent could otherwise miss.

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 high at 86%, so the baseline is 3. The description still adds real meaning: it clarifies the special '/' form and the '<project>/path' cross-project addressing convention, and explains that glob and sort apply to files (not folders).

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 one folder of a Basic Memory project') and immediately specifies the return shape: subfolders first, then files with title, date and id. It also explicitly distinguishes itself from the sibling bm_find, which does recursive name/frontmatter search.

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 concrete usage context: `bm_list('/')` with no project lists addressable projects, '<project>/path' lists inside another project. It names the alternative (bm_find) and the condition that selects it, plus notes where filtering (glob) and ordering (sort) belong.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds useful mode behavior beyond that: no-argument invocation returns an index, `page` reads exactly one page, and `query` lists pages matching every word. It does not discuss output formatting or error behavior, but the annotations cover the safety profile.

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

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

Three sentences, front-loaded with the core action and then mode-specific details. There is no filler; every sentence adds usable 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?

For a read-only manual tool with an output schema and strong annotations, the description covers all three invocation modes and enough examples to call it correctly. Minor gaps remain: no explicit sibling differentiation from `man`, and `output_format` is only inferable from the schema.

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

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

Schema description coverage is 67%, and the schema already documents `page` with examples and `query` with AND-matching semantics. The description largely repeats those examples and adds the `man -k` analogy, but does not cover the undocumented `output_format` parameter. A baseline 3 is appropriate since the schema does most of the work.

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

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

The description opens with a specific verb and resource: 'Read the Basic Memory manual.' It then distinguishes the three invocation modes (index, page, query), so an agent can tell this apart from note-reading or shell-manual siblings by resource scope.

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 clearly explains how the modes behave: no arguments returns the index, `page` reads one page, `query` searches pages by all given words. It gives examples such as 'bm-search(3)' and 'man -k', but does not explicitly say when to use this versus sibling tools like `bm_search` or `man`.

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 a non-destructive, non-idempotent mutation but say nothing about mechanics; the description fills that gap with extension rewriting, trailing-slash semantics, and optimistic concurrency via `expected_checksum` gated on the revision from bm_read. It also discloses the cross-project refusal rule, which an agent would otherwise only learn from a failed call.

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

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

Five sentences, each carrying distinct information: scope, destination semantics, extension rule, concurrency guard, and the cross-project exclusion. Front-loaded with the core action and no filler.

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

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

For a 6-parameter mutation tool with an output schema that covers return values, the description supplies everything an agent needs before calling: target selection, path formatting, concurrency safety, and the unsupported cross-project case.

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 83%, and the description adds real meaning on top: `destination` is project-relative, a trailing '/' changes its interpretation to a parent folder, and `expected_checksum` acts as a conditional guard rather than a plain value. `project` and `output_format` are left to the schema, which is acceptable.

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

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

States a specific verb pair (move/rename) and resource (a note or a directory), and binds each to its own parameter (`identifier` for notes, `path` for directories). An agent can tell what this does and which input shape applies without reading 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 rules out the cross-project case and prescribes the alternative workflow ('bm_read, bm_write there, then bm_delete'), which is genuine when-not guidance. It does not, however, differentiate itself from the sibling `move_note` tool, leaving a real ambiguity unresolved.

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=false, destructiveHint=false, idempotentHint=false, openWorldHint=false, so the safety profile is already carried by structured data. The description adds nothing about what `create` actually does to the filesystem — whether `path` must already exist, whether a directory is made, what happens on name collision, or whether creation can be undone. Since it is a non-destructive but non-read-only and non-idempotent tool, those omissions matter somewhat, but no contradiction exists with the annotations.

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

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

Everything is packed into a single front-loaded block with the command enum stated first, and no sentence is filler. The heavy nested-parenthesis style is dense but still parseable, costing a small amount of readability rather than correctness.

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, and the 11-parameter surface is large but mostly routed by the description. What remains thin is the create path semantics and the difference from the sibling project tools; both are real but secondary gaps rather than blockers to a correct 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 91%, so the baseline is 3, and the description earns a step above it by mapping parameters to commands (name/path/set_default/workspace belong to create; since/items/paging/project to recent) and by spelling out the `project` resolution chain: explicit project, else default project, else all projects. That cross-parameter precedence is not visible in the schema alone.

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

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

The description enumerates the three multiplexed operations (list, create, recent) and the resource is unambiguous: projects, grouped by workspace. An agent can tell what each command does without opening the schema. However, it never distinguishes this tool from overlapping siblings like list_memory_projects, create_memory_project, or recent_activity, so the agent must guess which entry point is canonical.

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 through per-command parameter mapping (list groups by workspace; recent falls back to the default project, or every project if none is set). That last clause is the only real selection rule given. There is no explicit when-to-use-this-instead-of guidance despite three sibling tools that appear to cover the same three operations.

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 safety (readOnly, idempotent, non-destructive), yet the description still adds real behavioral facts: line numbers count the whole file including frontmatter, max_tokens cuts at a section/paragraph boundary and returns a continuation line, images return as images and binaries as documents, and a missing note raises an error.

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 identity (what it reads, from what forms) before slicing options and the error/alternative note. Dense and largely waste-free, though the sentence about images/binaries sits slightly apart from the main reading flow.

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 9-parameter read tool with no output schema, the description covers input forms, slicing controls, truncation behavior, and metadata-only mode. Only the text/json output_format switch and include_frontmatter semantics are left 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?

With 67% schema coverage, the description goes beyond it by explaining that line counts include frontmatter (a semantics the schema omits), how max_tokens truncation behaves, and that include_content=false yields the checksum expected by bm_write/bm_edit. Minor gap: output_format and include_frontmatter are left entirely to the schema.

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

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

States a specific verb (Read) and resource (Basic Memory note or file) and enumerates the accepted identifier forms (path, permalink, memory:// URL, exact title), so an agent can match inputs to it immediately. It also distinguishes itself from the discovery sibling by routing missing notes to bm_search.

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 clear condition for the alternative ('A missing note is an error: find notes with bm_search') and explains the include_content=false mode as the checksum-fetch path used by bm_write/bm_edit. It does not, however, disambiguate against lookalike siblings such as read_note, view_note, or read_content.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine domain context the annotations can't: that a schema is itself a note with type: schema whose `entity` field names the type it describes. Return values needn't be explained given an output schema exists.

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

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

Front-loaded with the resource and a tight, per-command enumeration, then a definitional sentence. It is a dense run-on with some nested parentheticals, but every sentence carries useful information and 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?

For a 6-parameter, mutation-free, multi-mode tool with an output schema and full annotation coverage, the description supplies the one thing structured fields can't: the Picoschema concept and the command-to-target mapping. Omission of `project` and `threshold` is acceptable since the schema documents them well.

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 high (83%), so the schema already documents every parameter, including the enum values and threshold semantics. The description's mention of `note_type` and `identifier` largely restates what is in the schema, and it never touches `project` or `threshold`. Baseline 3 is appropriate.

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

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

The description names the resource (Basic Memory note schemas / Picoschema) and states the three concrete operations (validate, infer, diff) with the object each acts on. An agent can tell what this tool does without opening the schema. It does not, however, distinguish itself from the sibling schema_validate / schema_infer / schema_diff tools, which cover the same operations individually.

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?

Each of the three `command` values is given an explicit usage condition: validate covers one note_type, one note by identifier, or every type with a schema; infer derives a schema from a note_type's notes; diff finds drift against a note_type's schema. What's missing is any statement of when to prefer this multi-command tool over the per-command siblings.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add operational context, which it does: results are ranked by relevance, the default mode is hybrid when semantic search is available, and `lines` produces grep-like line output instead of excerpts. Pagination behavior (page/page_size) is left entirely to 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?

Front-loaded with the core search statement and ranking, then grouped by concern (query syntax, mode, narrowing, line output, scoping, alternative tool). Dense backtick-heavy phrasing for 22 parameters, but no sentence is redundant or padded.

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 an output schema exists, return values need no explanation, and the description covers the main decision points: mode selection, narrowing dimensions, and the handoff to bm_read. Only pagination and the specialist temporal/similarity parameters are unmentioned, and those are self-documented in the schema.

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

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

Schema coverage is 95%, so the baseline is 3; the description exceeds it by explaining query syntax (quoted phrases, AND/OR/NOT, tag:name), the meaning of each mode including permalink globs, and the intent of filters/path/identifier/lines. Specialist parameters (valid_at, time_kind, valid_overlaps, min_similarity, compact, pagination) get no prose treatment, but they are documented 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?

States a specific verb+resource ('Search a Basic Memory project, ranked by relevance') and immediately lists the dimensions that characterize the operation (modes, filters, line output). It routes to bm_read for full notes, so the agent can separate search from retrieval, though other similar siblings (search_notes, bm_find, grep) are never distinguished.

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 when-to-use signals for each mode ('hybrid (the default when semantic search is available)', permalink 'globs with *'), says query can be omitted to search by filters alone, and points to bm_read for reading full notes. It stops short of any when-NOT-to-use guidance or comparison against the overlapping search_notes/bm_find siblings.

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

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

Annotations already declare destructive=true and non-idempotent, but the description adds important behavior: an existing note is an error unless overwrite=true, and expected_checksum allows replacing only the revision read. It also explains title fallback behavior, which materially improves safe invocation.

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

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

The description is dense but front-loaded, starting with the core create-or-replace behavior before addressing modes, overwrite rules, and content format. Every sentence contributes operational guidance 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?

For an 11-parameter write tool with rich annotations, high schema coverage, and an output schema, the description supplies the critical missing behavioral context around addressing, conflict handling, and safe replacement. No essential invocation detail 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 91%, so the schema does most parameter documentation. The description still adds meaning beyond the schema by clarifying identifier path behavior, title precedence, overwrite defaults, and how expected_checksum relates to bm_read.

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: 'Create or replace a Basic Memory note.' It also distinguishes the tool from bm_edit for partial changes and explains the two addressing modes, so an agent can identify its role without inspecting 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 clearly states when to use identifier versus title plus directory, when overwrite is required, and that partial edits belong to bm_edit. It stops short of broader when-not guidance against other siblings, but the critical usage conditions are 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 already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds that 'json' excludes internal fields and 'text' is compact markdown, but says nothing about pagination limits, relation-traversal cost, or what 'context' actually contains beyond the output schema. Adequate, not rich.

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

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

Purpose and primary usage are front-loaded, but the bulk of the text is a bulleted URL/timeframe/format reference that largely restates the 100%-covered schema. It is organized but padded; a third of the length would still carry the same information.

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

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

With 10 parameters, an output schema, and full annotations, the description covers the one high-risk input (URL syntax) and the timeframe format thoroughly. Remaining gaps — depth semantics and pagination interaction with max_related — are minor since the schema and output schema cover them.

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; the description earns above baseline by documenting memory URL pattern matching ('folder/*'), allowed and forbidden characters, natural-language timeframes, and the json-versus-text output distinction in more concrete terms than the schema. It still does not explain 'depth' traversal semantics, which the schema only sketches.

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 ('Build context from a memory:// URI') with the intended outcome ('continue conversations naturally'). It does not, however, distinguish itself from siblings such as search_notes, read_note, or bm_context, so an agent must infer the boundary.

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?

'Use this to follow up on previous discussions or explore related topics' implies a scenario but never names an alternative tool or an exclusion condition (e.g., when to prefer search_notes or read_note instead). Usage is inferable but not routed.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description itself adds little behavioral context beyond saying it prints content; it does not explain range reads, section slicing, truncation, or frontmatter handling.

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

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

The description is two short sentences, front-loaded with the action and followed by the identifier form. There is no filler or repetition.

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

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

The tool has rich schema coverage, an output schema, and clear annotations, so the short description is not required to explain return values or parameter details. Still, for a read tool with several close siblings, the description omits enough selection guidance to be only minimally complete.

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

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

Schema description coverage is 100%, so the schema already documents identifier, section, start_line, end_line, max_tokens, include_frontmatter, project, and project_id. The description only reiterates the "<project>/path" identifier form, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: "Print a note's content." It also names the accepted identifier form. However, it does not distinguish this tool from overlapping siblings such as read_note, view_note, or read_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?

The description gives only the accepted identifier syntax, not when to use this tool versus alternatives. There is no guidance about when to prefer cat over read_note, view_note, read_content, or bm_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=false, destructiveHint=false and openWorldHint=false, so the write/safety profile is covered. The description adds genuinely useful side-effect context that annotations do not carry: the project directory is created if missing, and the optional change to the global default project. It omits error behavior for duplicate names and the fail-fast cloud routing noted only in the workspace 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?

Two short sentences, front-loaded with the action, with no filler. The opening line partially duplicates the title and the second sentence repeats 'Creates a new project', a minor redundancy.

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

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

An output schema exists and annotations cover the safety profile, so return values and read/write nature need not be explained. The description covers the key filesystem and default-state side effects; what is missing is guidance on duplicate-name failure and cloud-vs-local routing for a 5-parameter creation tool.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, giving a baseline of 3. The description names project name, path and the optional default flag but adds no semantics beyond what the schema states (uniqueness, workspace routing and output_format are all schema-only).

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?

Names a specific verb and resource ('Create a new Basic Memory project') and restates it with the two required inputs (name, path). It is distinguishable from list_memory_projects/bm_project by the verb, but it never explicitly contrasts itself with those 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?

There is no statement of when to use this versus list_memory_projects or bm_project, and no prerequisites such as the uniqueness constraint or that cloud credentials are needed when a workspace selector is supplied. The only usage hint is the incidental 'optionally sets the new project as default'.

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 beyond the destructiveHint annotation by stating deletion is permanent, that files are removed from disk, that is_directory recursively deletes everything under the path, and that a missing note returns false instead of erroring. These are exactly the behavioral facts an agent needs before an irreversible call.

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

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

Four short sentences, front-loaded with the action and scope, then the destructive consequence, then the recursive flag, then the not-found behavior. No sentence 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?

A mutation tool with an output schema still gets the salient return semantics (false on missing note) spelled out, and the recursive-deletion risk is explicit. Nothing needed to call it safely is missing.

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

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

Schema description coverage is 100%, so identifier, is_directory, project and output_format are already documented. The description restates the identifier forms and the is_directory branch but adds no syntax or edge-case detail beyond the schema, which puts it at 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?

States a specific verb (delete) and resource (note or directory) plus the accepted identifier forms. It is clearly distinguishable from the sibling read/edit/move tools 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?

Explains the key usage branch: pass is_directory=True to delete a whole tree, otherwise a single note is removed. It gives context but no explicit 'when not to use this vs edit_note/move_note' guidance or prerequisite checks.

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?

Although annotations already flag destructiveHint=true, the description goes well beyond them: it says append/prepend auto-create the note, that a failed count/heading check 'writes nothing', that replace_section consumes subsections by default, and that a stale checksum refuses the edit and never auto-creates. That is exactly the write/destroy surface an agent needs.

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 verb and the operation switch, and every clause carries operational detail. The single dense paragraph with stacked parentheticals is harder to scan than a short bulleted operation list would be, but there is little true filler.

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

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

For a 13-parameter, destructive, multi-mode tool with an output schema already covering return values, the description supplies the operation contract, failure semantics, atomicity guarantees, and concurrency precondition. Nothing an agent needs in order 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 the baseline is 3; the description still adds meaning the schema lacks — prepend landing after frontmatter, a heading lacking '#' being normalized to '##', and expected_replacements defaulting to 1. It does not touch project/workspace/project_id routing, but those are fully documented 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?

The first sentence states a specific verb and resource ('Edit a note in place') and the rest enumerates the six supported operations with their distinct semantics. It does not name write_note or delete_note as alternatives, so sibling differentiation is left to the reader, which caps it below 5.

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?

Selection among the six operations is spelled out (append/prepend create, find_replace requires existence and an exact count, section ops require an exact single heading). It also states when to pass expected_checksum. What is absent is guidance on when to choose edit_note at all versus write_note, which the description never mentions.

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 establish read-only, non-destructive, and closed-world behavior. The description adds valuable connector-specific behavior: unsupported MCP clients receive an error, and the return payload is a single text item containing JSON.

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: caller scope, input source, return shape, and fallback are all stated without wasted 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 single-parameter read-only fetch tool with annotations and an output schema, the description covers the necessary caller constraints, input expectations, return behavior, and the alternative tool. Nothing important 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?

Schema coverage is 100%, so the id parameter is already documented. The description adds useful context by saying the id should come from search results and that it may be a permalink, title, or memory:// URL.

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 fetches one document by id and returns a text item containing JSON. It also distinguishes the tool from sibling read_note by explaining that other MCP clients should use read_note instead.

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

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

It explicitly identifies the intended caller (OpenAI/ChatGPT connector), the source of the id (search results), and the alternative for unsupported MCP clients (read_note). This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the recursion trait and the project-qualified path form, which are genuine behavioral facts, but says nothing about pagination behavior, result caps or how the two modes interact (the non-combinability of name and meta lives only in 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?

Two sentences with no filler: the primary capability leads, and the path-syntax caveat follows. Nothing is restated and every clause carries information an agent needs.

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

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

With an output schema, full schema coverage and safety annotations, most structural burden is carried elsewhere, so the short description is defensible. What remains missing is disambiguation in a very crowded sibling set (ls, list_directory, search, search_notes, grep) — without that, an agent can call it but may pick the wrong tool.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters in depth; the baseline of 3 applies. The description adds only the '<project>/path' routing convention on top of that, which is a marginal increment rather than compensating for any 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 and resource: recursively listing files, either by name glob or by metadata predicates, with the extra path-routing syntax. It is clearly distinguishable from the mutation siblings (edit_note, move_note), but it never contrasts itself with the closest read siblings (ls, list_directory, search_notes, grep), which is the only thing separating it from a 5.

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 two modes it names (glob for name matching, metadata predicates for frontmatter filtering) and by the note that paths accept '<project>/path'. There are no explicit when-to-use or when-not-to-use statements and no sibling is named as the alternative for, say, plain directory listing or full-text search, so the agent has to infer routing.

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 and destructiveHint=false, so the safety bar is low. The description adds genuine behavioral context beyond annotations: empty-match returns no results, case-insensitive matching, and the reason to add context_lines. It doesn't discuss pagination behavior, but the added matching semantics are valuable.

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

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

Front-loads the core purpose and then layers mode details efficiently. Sentences each carry information, though the density around semantic/context_lines is slightly tight.

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?

Output schema exists, so return values needn't be explained, and annotations cover the safety profile. The description covers matching modes and the project prerequisite, leaving only minor gaps like pagination behavior for an 8-param 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 baseline is 3. The description adds real meaning beyond the schema for `pattern` (full-text keywords, not regex) and reinforces the semantic vs context_lines tradeoff and the project requirement, which the schema alone states more tersely.

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 ('Search note content in one project and return matching notes') and clarifies the matching mechanism ('Not a regex... full-text keywords by default'). It distinguishes itself from regex search by mechanism, though it doesn't name the competing sibling tools (search_notes, search) explicitly.

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

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

Gives clear conditions for the semantic mode ('semantic=True ranks by meaning instead') and for context_lines ('Add context_lines to get...'), plus the 'Requires project when several projects are addressable' prerequisite. It lacks explicit 'use X instead of grep' routing to siblings, so not a full 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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds only a brief note about filtering and depth control, without extra behavioral context such as pagination behavior or project resolution. There is no contradiction with annotations.

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

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

The description is a single front-loaded sentence with no wasted words. It immediately states the operation and the two main capability areas.

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 full schema, output schema, and annotations cover the mechanical details needed to invoke the tool. However, the description does not address project scoping or how this tool relates to sibling directory/listing tools, leaving some contextual gaps. It is minimally adequate given the rich structured metadata.

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 parameter meanings are already documented in the schema. The description mentions filtering and depth control at a high level but does not add syntax or semantics beyond what the schema provides. This meets the baseline for fully documented parameters.

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

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

The description states a specific verb and resource: 'List directory contents.' It also mentions filtering and depth control, which clarifies scope. However, it does not distinguish this tool from sibling list-oriented tools such as ls, bm_list, list_workspaces, or list_memory_projects.

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

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

The description gives no explicit when-to-use or when-not-to-use guidance. With several sibling listing tools present, an agent is left to infer when list_directory is preferable to alternatives like ls or bm_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 readOnly and non-destructive, so the safety profile is covered. The description adds meaningful behavior beyond that: cloud credentials gate whether cloud results appear, and results from both sources are deduplicated by permalink into a unified view — a non-obvious merging trait an agent should know about.

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, then scope, then the downstream identifier contract. Three short paragraphs, each adding distinct information with little repetition. Could be tightened slightly, but no sentence is wasted.

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

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

An output schema exists, so return-value detail is not the description's job; it still usefully flags the credential prerequisite and the merge rule. Minor omissions remain (e.g. whether the list is exhaustive or paginated), but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and the sole output_format parameter is fully described with an enum and default, so the schema already carries the meaning. The description adds no format details of its own; its external_id guidance concerns return values, not input semantics. Baseline 3 applies.

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

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

States a specific verb and resource ('List all available projects with their status') and immediately adds scope detail — local plus cloud sources merged by permalink. That merged-view behavior distinguishes it from sibling list tools like list_workspaces, so an agent can tell what it gets 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 explicitly routes downstream usage: take the returned external_id and pass it as project_id on other tools, and explains the condition where this matters (duplicate project names across workspaces). It stops short of naming a direct alternative or exclusion versus list_workspaces, but the use context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds that the tool returns tenant_id/type/role/name, which is mildly useful, but that information is largely duplicated by the output schema and it says nothing about ordering, empty results, or pagination for what could be a multi-tenant listing.

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 short sentence, front-loaded with the verb and resource and parenthetically listing the returned fields. No filler or redundancy.

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

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

This is a simple, zero-required-parameter read tool with a full output schema and complete annotations, so the description need not explain return values or safety. It is nearly complete; the only gap is that it gives no hint about the workspace/tenant context an agent needs before calling workspace-scoped 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?

Only one parameter (output_format) exists and schema description coverage is 100%, including a full enum documentation for text vs json. The description says nothing about output_format, so it does not compensate or add meaning — but the schema already carries that burden, making baseline 3 appropriate.

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

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

The description gives a specific verb and resource ('List available cloud workspaces') and even names the returned fields (tenant_id, type, role, name), so the agent knows exactly what it will get. It does not, however, distinguish this tool from the many other listing siblings (list_directory, bm_list, list_memory_projects) in terms of which resource domain it covers.

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

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

There is no statement of when to call this versus alternatives, no prerequisites (e.g. authentication or tenant context), and no exclusions. The agent must infer that this is the entry-point enumeration for workspaces before calling other workspace-scoped tools.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the routing behavior ('/' lists projects, '<project>/path' routes into a project), which is genuine added value, but says nothing about pagination behavior or the 'refuses when several projects are addressable' condition that the schema mentions.

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 tightly packed sentences with the core action front-loaded and the root-path special case attached directly. Nothing 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?

With an output schema present and full schema coverage, the description need not explain returns or parameters. It covers the main conceptual hurdle (root vs project-qualified paths); only the sibling distinction and pagination expectations are absent, which are minor.

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

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

Schema description coverage is 100%, so all five parameters including page, page_size and project precedence are already documented in structured fields. The description merely restates the path convention at a higher level, which is a baseline-level contribution.

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 ('List one directory level') and immediately clarifies the special root case. It does not, however, distinguish itself from the sibling list_directory / bm_list, which an agent could easily confuse with this tool.

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 no explicit guidance on when to choose this over list_directory or bm_list, and no stated prerequisites or exclusions. Usage is only weakly implied by the path-shape hints.

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 that this is a read-only, closed-world, non-destructive operation. The description adds no behavioral context beyond that, such as what kind of search is performed or how lookup differs from search. It does not contradict the annotations, but it contributes little.

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 front-loaded sentence with no filler or repetition. Every word supports the tool's core purpose.

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, read-only nature of the tool, a fully documented schema, and an output schema, the description is nearly complete for invocation. It could mention sibling tools like bm_man or clarify the page/search distinction, but those are minor gaps.

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 `page`, `query`, and the ignored `project`/`project_id` parameters in detail. The description only gestures at page lookup and search without adding syntax or constraints, so it meets the baseline but does not enrich parameter meaning.

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

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

The description states a clear verb ('Look up', 'search') and resource ('manual page', 'the manual'), so the tool's function is immediately understandable. It does not distinguish itself from likely siblings such as bm_man, which prevents a 5.

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 'or search the manual' implies the two usage modes, but it does not explicitly explain when to use `page` versus `query`, nor does it name alternatives. The schema notes mutual exclusivity, but the description itself gives only implied 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 the annotations by disclosing side effects: the file moves on disk and its index entry, observations and relations travel with it; the permalink is preserved unless update_permalinks_on_move is set; other notes' text is not rewritten. That tells the agent exactly what breaks and what doesn't, which the bare destructiveHint=false cannot.

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 action and the cross-project constraint, then spends the remaining space on destination-mode rules and move side effects. Dense but every sentence carries information; the long second sentence could be split for scanability.

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 handling return values and annotations covering safety, the description supplies everything else an agent needs: scope limits, mode selection, extension rules, and post-move state of permalinks and links. Nothing material is missing for a 7-parameter mutation 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, but the description adds real semantics: destination_path must keep the same file extension (with the .markdown→.md conversion rule), destination_folder preserves the original filename, and is_directory switches identifier/destination to directory-path interpretation. Only the project/project_id precedence and output_format are left to the schema.

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

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

States a specific verb and resource ('Move a note, or a whole directory with is_directory=true') plus a hard scope constraint ('within the same project; cross-project moves are refused'). This clearly separates it from read/search/edit 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 routes between the two destination modes ('give either destination_path ... or destination_folder (keeps the filename)') and states the cross-project exclusion. It does not, however, contrast the tool with siblings like edit_note or write_note, so an agent must infer that moving is not the way to rename-edit content.

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 readOnlyHint=true by disclosing transformation behavior: images are re-encoded as JPEG and downscaled to ~350 KB, other binaries return base64 as {"type": "document"}, and binaries above 350 KB are refused. These are decision-relevant constraints an agent could not infer from annotations or 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?

Two sentences, front-loaded with the core action and addressing modes, then the size/encoding caveats, then the routing rule. Every clause carries information; 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?

Covers addressing modes, size limits, encoding/transform behavior, and the sibling alternative; an output schema exists so return values need not be spelled out further. Nothing an agent needs 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 description coverage is 100%, so path, project, and project_id are already fully documented, including precedence of project_id. The description repeats the accepted path/permalink/memory:// forms but adds no syntax or resolution detail beyond the schema, making baseline 3 appropriate.

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

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

States a specific verb and resource ('Read a file's raw bytes') plus the accepted addressing forms, and explicitly scopes itself as 'without knowledge-graph processing', which separates it from read_note/search_notes. An agent can distinguish it from 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?

Explicitly routes markdown-note use cases to read_note when note resolution and fallback search are wanted, which is a concrete alternative-with-condition. It does not state any when-not-to-use case for this tool itself (e.g. preference among cat/read_note/view_note beyond that), but the primary fork is 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: the exact-title fallback, the fact that unresolved notes return suggestions instead of content, and the checksum-refresh use of include_content=false.

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

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

Three dense sentences that front-load the core read action and then layer the fallback and metadata-only mode. No wasted language, though it packs a lot into a single sentence block.

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 10 params at 100% schema coverage, an output schema present, and annotations covering safety, the description supplies the remaining behavioral essentials (fallback path, checksum use case, error suggestion behavior). An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by explaining the purpose behind include_content=false (refreshing the checksum for edit_note/write_note) and the page/page_size fallback semantics, going beyond restating parameter 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+resource ('Read a markdown note by title or permalink, optionally a numbered line range') and describes the fallback path when the identifier doesn't resolve. An agent can distinguish this read operation from search-based 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?

The fallback behavior ('if the identifier doesn't resolve directly... returns related-note suggestions') and the include_content=false guidance give clear context for when to use this tool. However, it does not explicitly name a competing sibling like search_notes or view_note to route between them.

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 read-only, non-destructive, closed-world profile, so the description's job is to add operational nuance — which it does by disclosing the implicit project-resolution and cross-project discovery fallback that would otherwise surprise an agent. It doesn't mention pagination limits or result ordering, but the output schema carries the return shape.

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 default-project behavior is usefully front-loaded, but the natural-language timeframe bullet list duplicates the schema's own timeframe examples verbatim in spirit, consuming roughly half the description with no new information.

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

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

With annotations, a full output schema, and 100% parameter coverage, the description only needs to resolve ambiguity — and it does resolve the main one (project vs. no project resolution order). Minor omission: no note on how timeframe interacts with the type/depth filters or what 'recent' ordering means in the returned feed.

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 every parameter in detail. The timeframe bullet list largely restates examples already present in the timeframe schema description, adding little beyond the schema; the project-defaulting sentence is the only genuine semantic addition.

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 concrete verb and resource ('Get recent activity') and scopes it to a project. An agent knows it retrieves a recent-items feed, though what counts as 'activity' is only inferable from the type parameter in the schema rather than the description.

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?

Explains the default-project fallback behavior ('with no project, this uses the configured default project... lists across all projects only when there is no default'), which is genuine usage context. However, it never names an alternative sibling (build_context, bm_search, search_notes) or states when this tool is the wrong choice over a search.

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 and destructiveHint=false, so safety is covered. The description adds domain context by explaining that a schema is a note with type: schema whose entity field names the described note type, but it does not clarify what counts as drift or how results are reported.

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 with no waste. The purpose is front-loaded and the schema definition follows as necessary context.

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

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

Output schema and annotations cover return values and safety. The description explains the core schema concept needed to call the tool correctly. A minor gap remains around what specific drift conditions are detected, but the essential information is 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?

Schema coverage is 75%, so the schema documents most parameters. The description adds meaning to note_type by explaining the schema-note relationship, but it does not mention project/project_id precedence or the output_format parameter beyond what the schema already provides.

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: detect drift between a schema definition and actual note usage. It also defines what a schema note is, which makes the purpose concrete. It does not explicitly differentiate itself from sibling tools like schema_validate or schema_infer.

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 tool is used for drift detection, but gives no explicit when-to-use guidance, no exclusions, and no comparison to relevant siblings such as schema_validate or schema_infer.

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 and destructiveHint=false, so safety is covered. The description adds conceptual context (what a schema note is) but does not disclose requirements such as minimum note counts, performance, or what the suggestion entails beyond the schema itself.

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

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

Two sentences with the core purpose front-loaded and a useful definitional follow-up. No wasted text, though slightly sparse.

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, annotations, and 80% param coverage, the description is largely complete. The only gap is lack of guidance on prerequisites (e.g., needing enough example notes) or how the suggestion should be interpreted.

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 80%, so the schema documents note_type, threshold, project, project_id, and output_format adequately. The description adds no parameter-level meaning beyond what the schema provides, 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?

States a specific verb+resource: 'Analyze existing notes of one type and suggest a Picoschema definition.' This clearly distinguishes it from sibling schema tools (schema_validate, schema_diff), though it doesn't name an alternative explicitly. The second sentence clarifies what a schema is, aiding understanding.

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?

Implies usage (analyze notes to derive a schema) but offers no explicit when-to-use guidance versus schema_validate, schema_diff, or manual schema creation, and no prerequisite conditions like having sufficient notes of that type.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: the default all-types sweep when no filters are given, plus a definition of what a schema object is, which the 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?

Three sentences, front-loaded with the action, second sentence giving the default scope, third defining the jargon. Nothing is padded and the ordering matches how an agent reads.

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, and read-only annotations cover the safety profile. The one remaining ambiguity is precedence when note_type and identifier are both provided, which the schema leaves implicit and the description does not resolve.

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?

At 80% schema coverage the baseline is 3, but the description adds the interaction rule the schema does not state: note_type and identifier together determine scope, and omitting both widens the sweep to all schema-bearing types. It stops short of saying what happens when both are supplied simultaneously.

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 ('Validate notes against their Picoschema definitions') and even defines the domain term 'schema'. It does not distinguish itself from the nearby schema_infer and schema_diff siblings, leaving the agent to infer which schema tool applies.

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 covers scoping behavior (omitting both filters validates every type that has a schema), which implies how to use it, but never states when to pick this over schema_infer or schema_diff, nor any prerequisites such as a schema existing for the type.

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, destructiveHint=false, openWorldHint=false, so safety is covered. The description still adds real behavioral facts beyond them: a hard cap of 10 results, a single text-item return envelope carrying JSON, and a hard failure mode for non-OpenAI clients. Slight redundancy with the existing output schema on the return shape keeps it from a 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?

Two sentences, zero filler. The adapter scope and return shape come first, the client restriction and fallback second — the correct front-loading for an agent deciding whether to call at all.

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 read-only tool with an output schema, an agent still gets everything it needs to avoid a wrong call: the client restriction, the error outcome, the result cap, and the fallback tool. 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?

Only one parameter with 100% schema description coverage ('Search query (full-text syntax supported by search_notes)'), so the schema already carries the semantics. The description mentions the query only as a field echoed back in the response, adding no syntax or format guidance beyond the schema. Baseline 3 for a fully documented single parameter.

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 (search adapter over the knowledge base) and immediately bounds it: 'top 10 search_notes matches' returned as one text item of JSON {results, total_count, query}. The first word 'OpenAI/ChatGPT connector' scopes it away from the general search_notes sibling, so an agent can tell them apart 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 names the exclusion and the alternative: 'Other MCP clients receive an unsupported-client error; use search_notes instead.' This is a rare case where both the when and the when-not are stated with a named fallback tool.

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

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

Goes well beyond the readOnly/non-destructive annotations: discloses the two-pass matching fallback for plain multi-term queries, the dynamic default search type, that valid-time filters exclude undated content, that `after_date` keys on last-updated content, and that results are ranked and paginated. These are non-obvious behaviors an agent could not infer from 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?

Front-loaded with purpose and the highest-value routing decision (single vs. multiple projects). It is a dense single block that would scan better as fragments, but nearly every clause carries distinct behavioral or parameter information rather than 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?

Covers the hard parts of a 21-parameter tool: query syntax, search-type defaults, entity-type defaults, temporal filtering, and result defaulting, plus a pointer to man page and read_note for follow-up. With an output schema present it need not describe returns, though pagination/ranking specifics are only gestured at.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `tag:name` query syntax maps to a tags filter, permalink `*` is a glob over the full path, `after_date` semantics, and the valid_at/valid_overlaps/time_kind model with an example. It leaves output_format, compact, and min_similarity entirely to the schema.

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

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

States a specific verb+resource (search notes/observations/relations) and immediately scopes it to one or several projects. It distinguishes itself from sibling readers by noting that full content requires read_note or cat.

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 routing rules throughout: use `projects`/`search_all_projects` for multi-project search, omit `query` for filter-only searches, `search_type` selection with a stated default, and the categories/valid-time rule that flips results to observations. It also names the follow-up tool (read_note/cat) once results are found.

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 that this is a read-only, non-destructive, closed-world operation. The description adds the multi-project addressing precondition, which is helpful, but does not otherwise elaborate behavior beyond what annotations and the output schema already cover.

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

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

The description is two short sentences with no wasted text, and the core purpose is front-loaded before the conditional requirement.

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

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

For a simple read-only listing tool with complete schema coverage, annotations, and an output schema, the description is largely sufficient. It covers the main addressing caveat but could be slightly stronger by naming when to use this instead of nearby alternatives.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description reinforces the project requirement but adds no new syntax or constraint 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: 'Show recently changed notes.' This is clear and actionable, though it does not distinguish the tool from similarly themed siblings such as recent_activity or search_notes.

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 provides one useful usage condition: 'Requires project when several are addressable.' However, it does not explain when to choose this over related tools like recent_activity, search_notes, or read_note.

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 say read-only/non-destructive; the description adds the non-obvious behavior that the payload is wrapped in display instructions, plus the edge case that not-found results bypass the wrapping. That's the kind of detail an agent can't get from annotations or 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?

Two to three short sentences, front-loaded with the core behavior, then the sibling routing, then the not-found caveat. 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?

Output schema exists so return shape needn't be spelled out, and the description still covers the wrapper transformation and the not-found exception. Everything an agent needs to choose and call it correctly is 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?

Schema description coverage is 100%, so identifier/project/project_id are already documented. The description only adds that resolution matches read_note, which is a thin hint rather than new parameter meaning — baseline 3 applies.

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

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

States a specific verb and resource ('Read a note') and immediately distinguishes the behavior from read_note via the wrapper ('return it wrapped in an instruction to display it as a markdown artifact'). An agent can tell exactly what this returns without opening read_note's 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 routing: 'Use when the user wants to see the note rendered; use read_note when you need the content yourself.' It names the alternative and the condition that selects each, leaving nothing 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 declare destructiveHint=true and idempotentHint=false; the description goes well beyond by explaining the default conflict-error behavior, the frontmatter merge semantics on overwrite (kept vs replaced keys, unparseable frontmatter discarded), and the checksum revision precondition. This is exactly the kind of consequence-level detail annotations can't carry.

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 conflict default, and every sentence carries non-obvious information. The overwrite/checksum sentence is dense and slightly run-on, but no content is wasted.

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

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

With an output schema present, return-value detail isn't needed, and the description still covers refusal modes, the advisory similar-notes behavior, and conditional overwrite. Nothing an agent needs to invoke this safely is missing.

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

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

Schema description coverage is 100%, so overwrite, expected_checksum, directory, and project routing are already documented in structured form. The description mainly restates those (directory required, overwrite+checksum pairing) and adds no syntax or format detail the schema lacks. Baseline 3 applies.

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

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

States a specific verb and resource ('Create a markdown note') and immediately distinguishes the create path from the mutate path by naming edit_note. An agent can tell write_note apart from edit_note, move_note, and read_note without inspecting 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?

Explicit routing: use edit_note for incremental changes, use overwrite=True to replace, pair overwrite with expected_checksum for conditional replacement. It also notes that the similar-notes result is advisory and non-blocking, so an agent won't mistakenly abort.

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