Cobrain

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds the useful create-if-missing behavior, but does not explain what happens on conflict beyond the marketing-style claim 'Never conflicts', which is vague rather than informative.

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

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

Two tight sentences, front-loaded with the core action and create-if-missing behavior, followed by the routing hint. 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 simple two-required-param mutation, the description covers purpose and routing but omits path format conventions and any hint on workspace behavior that the schema itself documents at length. Adequate but incomplete for an unfamiliar agent.

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

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

Schema coverage is 33%, so the schema leaves gaps. The description says nothing about 'path' or 'content' (both required), and the schema's workspace guidance is rich but the description does not reinforce or clarify the append target format. Baseline 3 given partial coverage, but it does not compensate for the two undocumented required params.

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 ('Add text at the end of a note') and even adds the create-if-missing behavior, distinguishing it from write_file by name.

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 the agent: 'prefer it to write_file for additions.' This is a direct when-to-use-vs-alternative statement naming a sibling tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real context beyond that: the intended caller restriction and the fact that output is HTML with author/timestamp/link fields. It doesn't mention error behavior or auth requirements, but the added value over annotations is clear.

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 compact sentences with zero waste; the caller restriction is front-loaded before the return details and the alternative-tool pointer. Every clause conveys distinct 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 two-parameter read tool with full schema coverage and no output schema, the description covers purpose, caller scope, the alternative tool, and the shape of the returned data. Nothing an agent needs in order to call or avoid it 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% (both 'ws' and 'path' are documented with format examples), so the schema carries parameter meaning. The description adds nothing about parameter syntax or constraints, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('returns one note rendered as HTML') plus the metadata returned (title, last update, author, link). It also distinguishes itself from the sibling read_file, so an agent can separate the two 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?

Explicitly scopes the caller ('Used only by the Cobrain app window (not by the model)') and names the alternative plus the condition that selects it ('To read a note in the chat, use read_file'). Both when-to-use and when-not-to-use are 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/destructiveHint/openWorldHint, so 'Read-only' is largely redundant. The description does add genuinely new behavior: the result cap of 25 notes and the fact that matching lines are returned, which the schema does not expose. It omits pagination/truncation behavior if more than 25 notes match.

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

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

A single dense sentence plus a short routing clause; the audience constraint and result bound are front-loaded, and every clause carries distinct 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 one-parameter read tool with no output schema, the description covers audience, semantics, result shape (25 notes with matching lines), safety signal, and the alternative tool. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single 'query' parameter is already documented as 'Words to look for; empty returns no results'. The description's 'full-text search' framing adds mild context but no syntax or matching-mode detail beyond the schema, so the baseline 3 applies.

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

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

Names a specific verb and resource ('full-text search across the brains you can read') and pins down scope with a concrete result bound ('up to 25 notes with their matching lines'). It also distinguishes itself from the sibling 'search' by audience (app window vs. model/chat), so an agent can tell the two apart 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?

Explicitly states the callers this tool is for ('Used only by the Cobrain app window (not by the model)') and names the alternative for the other case ('To search in the chat, use search'). Both a when-to-use and a when-not-to-use condition are present.

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

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

Adds substantive context beyond the annotations: storage location, the appended Markdown reference with its `link=false` opt-out, and explicit size ceilings (~3 MB for base64 data, 25 MB for server-side URL fetch). The two-step outcome for the 'neither' path (user upload link + signed PUT URL) is spelled out. Not a 5 because `confirm` and the refusal/error behavior for oversized input go unmentioned.

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 storage consequence, then the parameter decision rule. Dense but every clause carries operational meaning; the nested parentheticals make it slightly harder to scan than it needs to be.

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

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

For a 7-parameter mutation tool with no output schema, the description covers the storage side effects, size constraints, and the alternate upload flow well. Remaining gaps are `confirm`'s role and the note-vs-folder meaning of `path`, which matter but are secondary.

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

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

Schema coverage is only 43%, and the description does compensate for the two most important optional params (`data`, `url`) with size limits and mutual exclusivity, plus `link`. But `confirm` is undocumented in both description and schema, and `path` (note vs folder) and `name` are left entirely to terse schema text.

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

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

States a specific verb+resource ('Attach any file to a note') and immediately adds the side effect (stored under the branch's `attachments/`, Markdown reference appended). It doesn't explicitly contrast with the nearby `append_file`/`write_file` siblings, so an agent must infer the boundary, but the resource and outcome are unambiguous.

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

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

Gives a clear decision rule for the three input modes ('Give ONE of: data ... url ... or neither') plus a concrete triggering case: 'For a file the user gave you in the chat, call it with neither.' What's missing is any exclusion against sibling tools that also write files.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the side-panel UI behavior and stating that no input is taken, though it says nothing about what happens if the panel is already open or about result freshness.

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

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

Three short sentences, no waste, with the core behavior front-loaded and the disambiguation and return summary following. Every sentence earns its place.

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

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

For a no-parameter UI-opening tool with no output schema, the description covers the action, the side effect (panel opens beside chat), the return contents, and the sibling alternatives. Annotations carry the safety profile, so nothing an agent needs 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?

The tool takes zero parameters, so the baseline is 4. The description explicitly confirms this ('Takes no input') and additionally characterizes the payload shape (brains you can open plus their note list), which is more than the empty schema conveys.

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 action (opens the Cobrain app in a panel beside the chat) plus its purpose (browse and read the brain while chatting). It also distinguishes itself from the sibling open_brain by noting the panel-vs-fullscreen difference, so an agent can separate the two 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 routes the agent: open_brain for full screen, read_file/write_file to read or write a note directly. Both the alternative and the condition that selects it are named, 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 already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds real value beyond that: a missing template is seeded from a preset or generic one, files are 'born already written', and an existing folder only gains missing files (i.e. it will not overwrite). It stops short of describing the response or permission requirements.

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

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

Front-loaded with the core action, which is good, but the sentence is a run-on tangled with nested parentheses and dashes that make the workflow harder to parse than it needs to be. It is information-dense rather than concisely structured.

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

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

No output schema, so the description carries the return-value burden; it implies the created files but not the response shape. Given annotations cover the safety profile and the description covers the template-seeding and no-overwrite behavior, it is largely complete for a 6-param mutation tool, though param and response gaps remain.

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

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

Schema coverage is only 50%: `path`, `type`, and `fields` have no schema descriptions. The description compensates for `type` by explaining it is free-form and how a missing template is handled, but says nothing about `path` format or the `fields` object, leaving real gaps.

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 (create) and resource (unit) plus the mechanism (from `_templates/<type>/`), so an agent knows exactly what it does. However, it never references a sibling tool (e.g. list_units, write_file) to help disambiguate when this should be chosen over them.

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

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

Provides procedural guidance ('ask the user first if you do not know what it is and why it is being opened') and a scoping condition ('On an existing folder it only adds missing files'), which is useful. But it gives no explicit when-to-use/when-not guidance relative to alternative tools like write_file or start_project.

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

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

Beyond the destructiveHint/openWorldHint annotations, the description discloses genuinely useful behavioral facts: a 30-day recovery window, that only the brain owner can restore, that restoration happens via the Cobrain dashboard, and that no tool can see or restore the trash. This is exactly the kind of context a delete tool 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?

The description is a single information-dense sentence with the action front-loaded and consequences following. It is compact and wastes little, though the second clause runs long.

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 destructive tool with no output schema, the description covers the critical behavioral facts (reversibility window, who restores, trash invisibility). It is missing only usage routing against siblings and path-format guidance, which are secondary.

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 50%: the workspace parameter is well documented in the schema, but path has no description anywhere. The tool description says nothing about parameter meaning or format (e.g., what a valid path looks like), so it fails to compensate for the undocumented path 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?

The description states a specific verb and resource set ('Move a note, attachment or folder to the brain's trash'), clarifying that the delete is actually a soft-delete/move, which distinguishes it from the sibling move_file. It stops short of explicitly naming an alternative, but the action is unambiguous.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as move_file, nor any stated preconditions for deleting. Usage is only implied by the action described, leaving the agent to infer when a trash-move is appropriate.

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 the safe read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description only needs to add beyond that. It does add useful behavior: it emits a script to follow, duplicates are left for the agent/user to find by reading, and it asks once before content loss. The phrase 'anything that loses content' sits uneasily with destructiveHint=false, but the 'script to follow' framing makes it plausible these are follow-up actions rather than the tool's own writes.

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 'Dream:' identifier and intent, but the body is a single dense sentence with nested parentheticals ('duplicates you look for yourself, reading') that packs multiple ideas together. It is not bloated, but it is not efficiently structured either.

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 finder with four optional parameters, full schema coverage, and no output schema, the description is largely sufficient: it covers what is found, the routing triggers, and the confirmation caveat. Only the vague parameter mapping and the ambiguous content-loss clause leave small 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 all four parameters, and the baseline is 3. The description only loosely maps 'days' and 'path' (recent notes vs. one folder) and says nothing about 'saved' or 'workspace', so it adds little 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?

States a specific verb (finds) and concrete resources (broken [[links]], empty/still-template notes, long decision logs) scoped to recent notes or one folder, which clearly distinguishes it from siblings like find_notes or recent_changes. It falls short of 5 only because the purpose is buried in tangled, run-on prose.

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

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

Provides routing triggers ('dream', 'sogna', 'tidy up', 'riordina', the Dream email sentence), which helps an agent pick this tool by intent. However, it never states when NOT to use it or names alternatives (find_notes, recent_changes, list_tags), so the guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered externally. The description adds that the id originates from a search result and that output is JSON, but says nothing about failure behavior for a missing/invalid id or whether the note is rendered, which limits the added value.

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

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

Two short sentences with the core action front-loaded and no wasted words. The trailing 'Not ChatGPT? Use read_file.' is terse to the point of being ambiguous, which costs a little clarity for the space it saves.

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 annotations cover the safety profile. For a one-parameter read tool this is nearly complete; the only real gap is that the odd ChatGPT/read_file routing clause is never resolved into an actionable rule.

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

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

Schema description coverage is 0% — the single id property has no description in the schema — so the description must compensate. It does partially by stating the id should come from a search result's `id`, which is genuinely useful provenance, but it omits expected format or whether ids are stable across sessions.

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 (open a note) and identifies the id source as a search result's id, which separates it from generic reads. The sibling differentiation is attempted via the read_file reference, though the routing condition is cryptic rather than a clean distinction.

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

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

It names an alternative (read_file) with the condition 'Not ChatGPT?', which is a routing hint but a strange one — an agent has no reliable way to evaluate whether it is 'ChatGPT'. Usage is implied rather than clearly specified, and no when-not conditions are given for the fetch case itself.

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 nothing further: no result shape, no ordering, no behavior for unknown tags or tags in other workspaces.

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 words is not conciseness but under-specification; the single phrase is front-loaded but fails to earn completeness. A retrieval tool with a required filter needs more than a noun phrase.

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 two-parameter filtered-list tool with no output schema, the description omits what is returned, whether filtering is exact, and how it relates to the many sibling note-listing tools. Annotations cover safety only, leaving key retrieval semantics unaddressed.

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

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

Schema description coverage is only 50%: the required 'tag' parameter has no description in the schema, and the description does not compensate by explaining match semantics (exact tag vs substring, case sensitivity). The optional 'workspace' parameter is documented in the schema, so the description contributes nothing there either.

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 is a verbatim restatement of the tool title, adding no verb or scope beyond what the name already conveys. It does clarify that 'files' here means notes, but an agent still cannot tell what the tool returns or how it differs from find_notes, list_files, or list_tags.

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 when-to-use guidance, no exclusions, and no mention of alternatives such as list_tags or find_notes that also surface notes. The agent must guess whether this is the right entry point for tag-based retrieval.

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 the partial-match semantics (name or path part, wikilinks), but says nothing about exact vs fuzzy matching, multiple-match behavior, or result ordering.

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

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

A single front-loaded sentence with no filler; the matching mode and examples land immediately. It is appropriately sized for a simple lookup tool, though it could carry one more clause of routing guidance without bloat.

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 two-parameter read-only lookup with rich annotations and no output schema, this covers the essentials and the example values help clarify intent. The main gap is not distinguishing itself from the search siblings when content-based retrieval is needed.

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 50%: the workspace parameter is documented in the schema, but 'name' is not. The description partially compensates by giving concrete example values ('a unit folder, a [[wikilink]]'), which is useful, but it doesn't explain match rules or the required parameter's format constraints.

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 ('Find notes, folders and attachments') and clarifies the matching mode (by name or path part), which distinguishes it from full-text siblings like search/search_mentions. It stops short of explicitly naming an alternative, so the distinction must be inferred.

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 'by name or path part' phrasing implies the intended use case (locating a known item), but there is no explicit when-to-use guidance, no exclusions, and no pointer to search/search_mentions for content-based queries.

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 by structured data. The description adds the useful detail that results include size and that omitting path widens scope to the whole brain, but says nothing about ordering, pagination, or result limits for a potentially large 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 terse sentence with the scope condition front-loaded after the resource. Nothing is wasted, though the fragment style omits a verb and reads more like a label than an instruction.

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 is the only source of return-value information and does provide '(with size)'. For a listing tool that can span an entire brain, the absence of any note about result volume, ordering, or truncation leaves a meaningful gap.

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 50%; the workspace parameter is documented in the schema but path has no description. The description compensates by defining path semantics ('under a folder' / omit for whole brain), which is exactly the missing piece, so it adds real meaning beyond the schema.

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

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

The description states the resource clearly: notes and attachments under a folder, with a scope modifier (omit path for the whole brain). It is distinguishable from find_notes/search/files_by_tag by naming the listing scope, though it never uses an explicit verb and leans on the tool name to imply 'list'.

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

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

It gives one conditional usage rule ('omit path for the whole brain'), which is genuinely useful. However, it never says when to prefer this over sibling enumeration/search tools such as find_notes, files_by_tag, or list_units, so the guidance is partial rather than comparative.

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 only added context is that results include counts, which is a small but real disclosure about the return payload; nothing is said about scope, ordering, or auth.

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 undeniably short, but this is under-specification rather than conciseness: a two-word noun phrase carries no actionable instruction and front-loads almost nothing.

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 should at least sketch the return shape, and it should route the agent away from files_by_tag. Annotations cover safety, but for a listing tool with a sibling in the same domain the definition is too thin to be 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?

There is one optional parameter with 100% schema description coverage, including a clear note to usually omit it and the accepted value forms (brain id, 'mine', owner name/email). The description adds nothing, but per the baseline rule the schema does the heavy lifting.

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

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

The fragment 'Tags with counts.' names the resource and hints at the return shape (counts), but supplies no verb and does not distinguish it from the sibling files_by_tag, which also deals with tags. It reads closer to a title stub than a tool 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?

There is no when-to-use guidance at all, and no mention of the sibling files_by_tag that an agent might otherwise select. Nothing tells the agent what situation this tool is for versus alternatives.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false). The description goes beyond them by disclosing the default filtering rule (closed units excluded unless all=true) and the shape of returned fields, which is real behavioral context.

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 telegraphic sentences, no filler; the resource definition and its returned fields are front-loaded, with the filtering caveat last. Density is high but a few fragments ('open sub-units', 'closed ones') are slightly cryptic.

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 field list carries the return-value burden reasonably well, and the default-exclusion rule is stated. However, nothing covers the undocumented `type` parameter, pagination/size limits, or what values 'status' and 'type' can take.

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

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

Schema coverage is only 33%, and the description compensates for one gap by explaining the `all` flag's effect. The `type` parameter remains undocumented in both description and schema, so compensation is partial rather than complete.

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 defines the resource concretely ('Units (folders with _about.md)') and enumerates the fields it returns, which is far more than the bare tool name offers. It does not name or contrast with the nearest siblings (list_files, list_tags, list_workspaces), so it falls short of 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?

'Closed ones only with all=true' gives one explicit conditional that governs behavior, but there is no overall when-to-use guidance and no routing to alternatives like list_files for plain files. Usage is implied rather than stated.

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 one genuinely useful behavioral detail not in structured fields: the first line of output identifies the connected account, which matters because there is no output schema.

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

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

A single short sentence with two clauses, no filler or redundancy. The semicolon construction is slightly awkward and the output detail is tacked on rather than front-loaded, but nothing is wasted.

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

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

For a simple zero-param, read-only listing tool with no output schema and annotation-covered safety, the description is close to adequate. It explains the result set and hints at output shape, but the 'first line' detail is partial and it omits ordering/completeness of the shared-brain set.

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

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

The tool takes zero parameters, so the schema offers nothing to document and there is no parameter semantics for the description to clarify. Baseline 4 applies for a no-parameter tool.

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 fragment "Your brain and those shared with you" conveys the resource scope (brains/workspaces you own plus shared ones) but never states a verb like 'list' or 'returns'. Combined with the tool name it is inferable, but the description alone is vague rather than a specific verb+resource statement.

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 guidance on when to call this versus siblings such as open_brain, settings_read, or load_context. The only clause ('first line: the account you are connected as') describes output, not when or why to invoke the 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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description still adds real behavior: deterministic ordering (rules, _about.md, _ai.md, context and decisions first), exclusion of closed sub-units, and the fact that the header enumerates notes that did not fit. It does not explain how the truncation is bounded, which keeps it short of 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 dense sentences with no filler; the most decision-relevant facts (what you get, ordering, the overflow escape hatch) come first. The telegraphic style borders on cryptic but never wastes a clause.

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

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

For a zero-required-param, read-only aggregator with no output schema, the description covers ordering, skipping, and the overflow header, which is the core of what an agent needs. Gaps remain on path/tag interaction and on how truncation interacts with max_chars, so it is adequate rather than 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 only 25% (just the workspace param), so the description must compensate, and it partly does: it clarifies the folder-vs-tag duality implied by the path and tag params and hints that output size is bounded (relevant to max_chars). It does not state whether path and tag are mutually exclusive, precedence rules, or what max_chars defaults to.

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

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

States a specific resource ('all notes under a folder (or tag)') and the delivery form ('in one blob'), which distinguishes it from the single-note read_file sibling it explicitly names. The verb is implied rather than stated and the phrasing is compressed, but an agent can identify the operation.

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

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

It names read_file as the follow-up for material that was trimmed ('read_file those you need'), which is a useful conditional routing hint. However it never says when to prefer this bulk load over siblings like list_files, files_by_tag, or find_notes, so the primary selection guidance is left to inference.

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

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

Annotations already flag destructive/write/openWorld, and the description goes well beyond them: attachments under the path travel with the move, links to them in notes are rewritten, write access is required on both ends, and cross-brain moves are restricted to the source brain's owner. These side effects and permission constraints are not derivable from the 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?

Three compact sentences, purpose front-loaded, then side effects, then the one parameter needing special care. No filler and nothing repeated from the schema.

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 destructive, 4-parameter move tool with no output schema, the description covers permissions, side effects (attachment travel, link rewriting) and cross-brain limits. It omits collision/overwrite behavior and any hint of failure modes beyond the refused-branch note 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 50%, and the description compensates by clarifying to_workspace as a cross-brain destination with an owner-only restriction, and by defining 'from' implicitly as a path prefix ('attachments under the path travel with it'). The 'from'/'to' parameters still have no explicit description in either the schema or the text, leaving a small 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 pair and resource scope: 'Rename or move a note, attachment or folder.' The rename/move semantics plus the attachment/folder coverage clearly separate it from write_file, patch_file, append_file and delete_file in the sibling list. It stops short of naming an alternative explicitly, so it is not 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?

Provides preconditions rather than usage routing: '(write access on both ends)' and 'to_workspace moves it into another brain (only the source brain's owner can).' It never says when to choose this over a write/patch/delete sibling or what happens if the destination already exists. Usage is implied by the constraints rather than spelled out.

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 useful context that this opens the app full screen within the ChatGPT sidebar, but says nothing about what happens afterward (focus, return value, error conditions).

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

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

A single, front-loaded sentence with no padding. Every word earns its place for such a simple action.

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

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

For a zero-parameter UI-invocation tool with no output schema, the description covers what the action does and where it surfaces. It could add minor detail on post-invocation behavior but nothing essential 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?

The tool takes no parameters, so there is nothing to document in the description; the 0-param baseline of 4 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 ("Opens") and a specific resource ("the Cobrain app"), and notes the surface where it appears (full screen / ChatGPT sidebar). It is clear what the tool does, though it doesn't explicitly distinguish itself from lookalike siblings such as brain_panel or app_note.

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 when-to-use, when-not-to-use, or alternative guidance. It does not tell an agent whether this is a prerequisite for other Cobrain tools or when opening the app is appropriate versus unnecessary.

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 carry destructiveHint=true and readOnlyHint=false, so safety is covered; the description still adds real behavior the annotations can't express — unique-match requirement, the replace_all escape hatch, and that an empty new_text deletes content. It omits what happens on a failed/no match and whether the edit is atomic.

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 action, then the matching contract, then the edge case. No filler and nothing repeated from the schema.

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 destructive mutation tool with no output schema, the description covers the failure-prone behaviors an agent needs (exact copy, single occurrence, deletion via empty string). Missing only error/return behavior on no-match and multi-match without replace_all.

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

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

Schema coverage is only 20% (just workspace), so the description must carry the load, and it does: old_text matching semantics, new_text empty-string deletion, and the role of replace_all are all explained in prose. Only `path` is left to obvious inference.

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

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

States a precise verb+resource+scope: replace old_text with new_text in an *existing* note, which implicitly separates it from creation tools. It never names the adjacent siblings it competes with (write_file, append_file), so an agent must infer the boundary rather than read it.

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

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

Gives a concrete precondition ('old_text is copied exactly from read_file') and the escalation path when the condition fails ('add context, or replace_all: true'). No explicit when-not-to-use or named alternative among siblings, so it stops just short of a 5.

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

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

Annotations already cover the safety profile (readOnly=true, destructive=false, openWorld=false), and the description goes well beyond them, disclosing return-format behavior per attachment type (images inline, Office/iWork/RTF as text, spreadsheets as CSV, video as frames, otherwise a 1-hour signed URL) and the pagination behavior for long PDFs. This is exactly the behavioral context that 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?

Front-loads the core purpose in the first clause, then appends the base-version contract and the attachment-format matrix. Dense but every clause carries distinct information; the semicolon-chained list of formats is compact if slightly breathless.

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

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

With no output schema, the description correctly shoulders the burden of describing return shapes, and it does so per attachment type plus the PDF pagination follow-up. It stops short of noting any size limits or failure modes, but for a read tool it is otherwise complete.

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

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

Schema coverage is 67%, with `path` and `pages` documented in-schema; the description adds workflow meaning to `pages` by explaining that the reply tells the agent which page range to request next on long PDFs. Only `workspace` is left entirely to the schema, which is a minor gap given its "usually omit" default.

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 read path from the write path by explaining the version token that feeds write_file `base`. It reads clearly as the file-content reader among siblings, though it never explicitly contrasts itself with list_files, fetch, or find_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?

The description implies the read→write workflow by naming write_file `base`, which is useful cross-tool guidance. However it offers no explicit when-to-use or when-not-to-use guidance relative to the other read-oriented siblings (list_files, fetch, find_notes), leaving selection to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the content shape ('who and when'), which is genuinely useful and not in the annotations, but says nothing about ordering, default size, or freshness window.

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 with no filler, and the key content ('who and when') is front-loaded. It is efficient, though its terseness means information is omitted rather than merely compressed.

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 listing tool with safety fully covered by annotations and no output schema, the basics are present, but ordering guarantees, default limit, and the recency window are all unspecified. An agent can call it, but cannot predict result size or ordering.

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

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

Schema coverage is only 50%: the 'workspace' parameter is documented but 'limit' has no description anywhere. The description supplies no parameter information at all, so it fails to compensate for the undocumented limit; the agent cannot tell its default or its units.

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 (recently changed notes) and the contents of each entry (who and when), which tells an agent clearly what it returns. It does not, however, distinguish itself from near-siblings such as list_files, find_notes, or search, so the agent must infer the difference from the names alone.

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

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

There is no statement of when to choose this tool over list_files, find_notes, or search, nor any prerequisite or exclusion. The agent is left to infer usage entirely from the title and sibling names.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real value on top: the 2-4 keyword limit, the return shape (paths, dates, matching lines), the caveat that excerpts are not the note, and the meaning of the below-`Maybe related`/`Similar in meaning` sections. It stops short of pagination or ranking-limit details.

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

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

The core purpose is front-loaded in the first clause, and every following sentence adds result-interpretation or parameter detail. It is dense and slightly run-on with inline markup, but there is little 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 2-parameter, read-only tool with no output schema, the description covers purpose, return content, result-section semantics, the read_file caveat, and both parameters, which is what an agent needs to call and use 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?

With 0% schema coverage the description must carry both parameters, and it does: query is framed as '2-4 keywords' and path is explained as narrowing to a branch. Both are given meaning beyond the bare schema, though neither is elaborated in depth.

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: 'Full-text search over your brain and the shared ones, 2-4 keywords.' It is clear what the tool does, but it never names or contrasts sibling tools like find_notes or search_mentions, so sibling differentiation is left to inference.

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

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

It gives a strong usage directive for one case ('read_file before answering') and explains how to interpret result sections. However, it never states when to choose this tool over find_notes, search_mentions, app_search, or recent_changes, so selection guidance is only implied.

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 no further behavioral context such as what the search covers, what it returns, or any limits.

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 text is short and contains no fluff, but it is fragmented and under-specified rather than appropriately structured. The two fragments do not form a clear, front-loaded explanation of the tool.

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

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

For a tool in a large sibling set, the description is missing essential information about what the tool does and when to use it. Although an output schema exists and annotations provide a title and safety hints, the description itself remains incomplete.

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

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

There is one required parameter, 'query', with 0% schema description coverage. The description does not explain what the query should contain or how it is interpreted, so it fails to compensate for the missing schema documentation.

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

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

The description is a noun phrase rather than a clear verb+resource statement: 'ChatGPT composer @-mentions.' It does not explicitly say that this tool searches mentions or what resource is being searched, leaving the agent to infer the action from the tool name.

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 fragment 'Others: find_notes.' points to an alternative sibling but gives no condition for choosing between them. There is no explicit when-to-use guidance or exclusion criteria.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds specificity beyond that: it never touches notes and reads only one scoped setting, which usefully bounds the read behavior.

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

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

Two tight clauses with the verb and resource front-loaded; the parenthetical definition of 'Dream cadence' and the read-only guarantee each earn their place with 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 zero-parameter read tool with an output schema that carries return values, the description supplies everything needed: what it reads, its single-setting scope, and its non-mutating nature. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds nothing about inputs, and the empty schema leaves no ambiguity to resolve.

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 (Cobrain settings) and narrows scope to a single setting, 'only the Dream cadence (how often Cobrain suggests tidying up the brain)'. This clearly differentiates it from the sibling settings_update, which writes settings.

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 establishes clear context (inspect settings rather than modify them) and its 'only the Dream cadence' scoping implicitly tells the agent not to expect other settings. It stops short of explicitly naming settings_update as the write counterpart, so it isn't a full when/when-not/alternatives statement.

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 and destructiveHint=false, so the safety profile is covered; the description adds useful scope detail that only one preference is affected and notes are untouched, confirming a low-blast-radius write. It stops short of mentioning idempotency or whether unsent/unchanged values are ignored.

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 compact sentences with no filler, front-loading the action and immediately bounding scope. The parenthetical value list is dense but earns its place by closing a schema gap.

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 for a one-key settings write the description covers purpose, scope, and valid values. Missing only auth/permission expectations and the exact parameter shape, which are modest gaps for a tool this narrow.

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

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

Schema coverage is 0% and the single parameter is a nested object ('set' containing 'dream'), so the description must carry the load. It supplies the permissible values (weekly, monthly, never) that the schema omits, but never explains the nested 'set.dream' shape, leaving the invocation path ambiguous.

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 ('Save the Cobrain settings') and narrows the scope to exactly one preference, the Dream cadence, with its allowed values. This cleanly separates it from the read-side sibling settings_read and from note-mutating tools like write_file or patch_file.

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?

Places the tool in a clear workflow context ('settings changed in ChatGPT's plugin settings page') and rules out note editing ('never touches notes'), which is real when-not guidance. It does not, however, explicitly name settings_read as the alternative for inspecting settings, so the routing is implied rather than stated.

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

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

The description says to 'set up a new unit' — a creation/mutation action — while annotations declare readOnlyHint=true and destructiveHint=false. A read-only tool setting up a new unit is a direct contradiction that could mislead the agent about side effects.

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

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

Two short sentences, front-loaded with the action and followed by triggers; no filler. Minor cost is spent on the parenthetical gloss rather than on differentiating siblings.

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

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

For a zero-parameter, no-output-schema tool the description is minimally sufficient, but it leaves 'unit' undefined, omits any relationship to create_unit, and is inconsistent with its own read-only annotation, so an agent lacks what it needs to invoke this confidently.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the schema or description to disambiguate. The description cannot add parameter meaning because none exist.

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 general action ('set up a new unit') and glosses the resource with '(client, project...)', which helps, but 'unit' and 'Script' are non-standard terminology left undefined. It also fails to distinguish this from the sibling create_unit, so an agent cannot tell which creation path 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?

It gives concrete triggers ('nuovo cliente', 'start project', 'track someone/something new'), which is useful when-to-use signal. However, it names no exclusions and no alternative tool (e.g., create_unit), so the boundary against siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond them: what the briefing contains, the fixed English file/key conventions across all brains, frontmatter semantics (status: active|closed, context: folders always loaded), and that _decisions.md is handled by append_file. It does not mention permissions or result size/pagination, but the annotation coverage lowers the bar.

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 key directive ('Call FIRST...') is front-loaded, and the paragraph is information-dense with no filler. However, heavy parenthetical nesting and the trailing file-structure conventions make it a somewhat run-on block; some frontmatter detail is more domain reference than call guidance.

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

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

With no output schema, the description carries the burden of describing returns and does so (contents of the briefing plus the change history window). Annotations cover the safety profile and the required parameter is explained. It is complete enough to invoke correctly; only the exact shape of the returned briefing is left implicit.

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

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

Schema coverage is only 50%: `workspace` is documented in the schema, but the required `unit` parameter has no schema description. The description compensates by defining `unit` ('path or name') and explaining what a unit is. This meaningfully fills the gap left by the schema for the required 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?

The description defines the resource precisely (a unit = a folder containing _about.md, such as a client or project) and enumerates what the session returns: rules, _about.md, _ai.md, context, decisions, open sub-units, last 15 changes. It distinguishes itself from load_context, which it positions as the follow-up for sub-folders. The only weakness is that the actual act (producing a briefing) is implied by the content list rather than stated as a verb.

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

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

It gives an explicit trigger ('Call FIRST when the user names a unit') and an explicit next step ('Then load_context on the sub-folder you need'), naming the sibling tool by name. The when-to-use and the hand-off are both spelled out, 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 already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds real value beyond that: it warns that a short content string 'erases the rest' and that passing `base` guards against clobbering concurrent edits (with a re-read/merge instruction). It does not cover permission/auth or the workspace refusal path, so not 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 tight sentences, zero filler, and the destructive scope is front-loaded before the alternatives. Every clause earns its place.

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

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

For a 5-param mutation tool with no output schema and 40% schema coverage, the description covers the highest-risk semantics (full replacement, concurrency guard, sibling routing). The unmentioned `overwrite` flag and the workspace refusal path are minor residual 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 coverage is only 40%, and while the description usefully explains `base` and the destructive effect of `content`, it says nothing about `overwrite`, and only the schema covers `workspace`/`path`. It compensates partially but leaves gaps, so the baseline-for-low-coverage 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+resource ('Create a note or REPLACE its whole content') and immediately names the two sibling tools it is not (append_file, patch_file). An agent can distinguish this from every other file tool 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 routes: 'To add, use append_file; to change one part, patch_file', and flags the `base` parameter as required when replacing. This is exactly the when/when-not/alternatives guidance the dimension asks for.

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