Server Quality Checklist

Tool Scores

• brain_attach_urlB
  3.3/5.0
  Behavior3/5

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

  The description discloses two useful behaviors beyond the name: duplicate-URL avoidance and the name-empty fallback to page title. However, since there are no annotations, it does not cover mutation side effects, permissions, error behavior, or return value, leaving a transparency gap for a write operation.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the main action, and every clause adds useful information. There is no redundancy or filler.

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

  Completeness3/5

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

  Core behavior and the duplicate check are explained, but the description does not mention the return value, what happens on duplicate (reject vs. silently skip), or any prerequisites like the thought/brain existing. With no output schema, these missing operational details reduce completeness.

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

  Parameters3/5

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

  Schema description coverage is 75%, covering url, name, and brainId with meaningful descriptions. The tool description adds no new parameter meaning beyond what the schema already states (e.g., name empty behavior is already in the schema), and thoughtId remains undocumented.

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

  Purpose4/5

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

  The description uses a specific verb ('Attaches') and resource ('a link to a thought'), making the action clear. It also adds scope by mentioning duplicate-avoidance, which distinguishes it somewhat from generic linking tools, though it does not explicitly contrast with sibling tools like brain_link.

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

  Usage Guidelines2/5

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

  The description gives no explicit guidance on when to use this tool versus alternatives such as brain_link or brain_ingest. It provides a behavioral note about duplicates and a naming hint, but no when-to-use or when-not-to-use context.

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

• brain_linkA
  4/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of disclosing behavioral traits. It fails to mention side effects, idempotency, permission requirements, or behavior on duplicate links. It is implied to be a mutating operation but does not explicitly state this or describe the response.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core action. The second sentence provides usage context and examples with no wasted words. Every sentence earns its place.

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

  Completeness4/5

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

  Given the tool's moderate complexity (5 params, 1 enum) and the absence of annotations and output schema, the description is fairly complete. It covers purpose, when to use, and example link labels, but it omits behavioral details like whether links are directed, return values, or prerequisites (e.g., existing thoughts). The schema covers all parameters, so the description adds sufficient context overall.

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

  Parameters4/5

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

  Although schema coverage is 100% and the baseline is 3, the description adds value by giving concrete example labels for the 'name' parameter ('motivates', 'solved by', 'contradicts') and implicitly explains the from/to relationship via 'links two thoughts'. It does not explain the 'relation' enum, but the schema does.

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

  Purpose5/5

  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: 'Links two thoughts.' This clearly distinguishes it from sibling tools like brain_create_thought or brain_update_thought. It also explains the conceptual role of links in building a graph, further clarifying its unique purpose.

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

  Usage Guidelines4/5

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

  The description explicitly states when to call it: 'Call it when you spot a meaningful relationship between existing thoughts.' It provides clear invocation context, though it does not explicitly mention when not to use it or name alternative tools for creating thoughts.

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

• brain_recent_changesA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that output is in 'plain language' and focuses on changes over a period, which implies a read-only operation. However, it does not specify what types of changes are included (e.g., creations, edits, deletions) or the exact format of the response, leaving some ambiguity. This is adequate but 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.

  Conciseness5/5

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

  The description is only two sentences long, with the purpose front-loaded in the first sentence and usage examples in the second. Every sentence earns its place, and there is no redundant or extraneous wording.

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

  Completeness4/5

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

  Given the tool's simplicity (3 parameters, no output schema), the description is fairly complete. It explains the tool's purpose and gives concrete usage scenarios. However, it does not detail the return structure or edge cases (e.g., empty results), so it's not a perfect 5, but it is well-suited for an agent to select and invoke the tool.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already fully documents all three parameters. The description adds no additional parameter-specific information beyond what the schema provides. Baseline for high coverage is 3, and the description does not improve on that.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'What changed in the brain over a period, in plain language.' It uses a specific verb (changed) and resource (brain), and the mention of digests and work in progress differentiates it from sibling tools like search or get_thought. The purpose is immediately identifiable and distinguishes from alternatives.

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

  Usage Guidelines4/5

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

  The description gives explicit use cases: 'Call it for digests' and 'to understand what work was in progress before continuing it.' This provides clear context for when to use the tool. However, it does not mention when not to use it or name specific alternative tools, so it falls short of the highest bar.

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

• brain_activateA
  4.1/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It clearly conveys a display action ('opens ... on screen') and implies no side effects via 'show the person a result.' It doesn't discuss edge cases, but for a simple UI-activation tool this is adequate.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the action, and every word earns its place. No redundancy or filler.

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

  Completeness4/5

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

  For a simple tool with no output schema, the description covers what it does, when to use it, and gives a concrete example. It doesn't discuss errors or prerequisites, but those are likely unnecessary for a basic UI-opening action.

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

  Parameters2/5

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

  The description adds no parameter information. The schema covers brainId with a helpful instruction, but thoughtId is completely undocumented. With 50% schema description coverage, the description should have compensated by explaining thoughtId, but it doesn't.

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

  Purpose5/5

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

  The description states a specific action with a clear resource: 'Opens a thought in the user's TheBrain app on screen.' It also provides a concrete use case ('show the person a result') that distinguishes it from sibling tools like brain_get_thought or brain_create_thought.

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

  Usage Guidelines4/5

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

  It provides explicit context on when to call the tool: 'Call it to show the person a result — for instance a structure you have just created.' While it doesn't explicitly name alternatives or exclusions, the guidance is clear and actionable.

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

• brain_tagA
  4.1/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses a notable behavior—that both add and remove can happen in one call—and explains the special nature of tags. However, it does not mention potential side effects, error handling for invalid IDs, or whether operations are idempotent, leaving significant behavioral gaps.

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

  Conciseness5/5

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

  The description is three sentences, each earning its place. It front-loads the primary action, then provides essential context about tags and the combined add/remove capability, with no filler or redundancy.

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

  Completeness3/5

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

  The description covers the core workflow: attaching/removing tags, sourcing tag IDs, and creating tags. However, it omits details about the required thoughtId parameter (e.g., where to get it), how to handle cases where both add and remove are empty, and any return behavior. These gaps make it incomplete for a tool with no output schema and no annotations.

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

  Parameters4/5

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

  Schema coverage is 75% (add, remove, brainId have descriptions; thoughtId does not). The description adds semantic value beyond the schema by explaining that tags are separate thoughts and that identifiers come from brain_list_types_and_tags, enriching the 'add' and 'remove' parameter meanings. However, thoughtId remains undocumented in both schema and description, preventing a higher score.

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

  Purpose5/5

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

  The description clearly states the tool 'attaches and removes a thought's tags', using a specific verb and resource. It distinguishes itself from sibling tools by explaining that tags are special thoughts and directing users to brain_list_types_and_tags for identifiers and brain_create_thought for creating tags, which clarifies its unique role.

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

  Usage Guidelines4/5

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

  Provides clear usage context by explaining the prerequisite steps: obtaining tag identifiers from brain_list_types_and_tags and creating new tags via brain_create_thought. It also notes that a single call can both add and remove, but it does not explicitly describe when not to use this tool compared to alternatives like brain_update_thought, so it lacks exclusions.

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

• brain_append_noteA
  4.2/5.0
  Behavior4/5

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

  No annotations provided, so description carries the full burden. It discloses non-destructive behavior and auto-creation of a note when none exists. This is sufficient for a simple append operation, though it doesn't mention return values or side effects beyond creation.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the core action and outcome. Every phrase adds value; no filler.

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

  Completeness4/5

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

  For a 3-param, no-output-schema tool, the description covers the key behavior, creation semantics, and non-destructiveness. It could mention when not to use (if replacing note) or return behavior, but nothing critical is missing.

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

  Parameters3/5

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

  Schema provides descriptions for brainId and markdown, but thoughtId is undocumented. The description adds general context about accumulating material but not parameter-specific semantics. With 67% coverage, it's adequate but not exceptional.

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

  Purpose5/5

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

  Clearly states the action (appends text) and result (to end of a note without erasing anything), and positions it as the main way to accumulate material. Distinguishes from likely sibling brain_set_note by emphasizing non-destructive accumulation.

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

  Usage Guidelines4/5

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

  Explicitly identifies when this tool is the main choice ('main way to accumulate material on a thought'), and implies alternatives by stressing that it does not erase. It doesn't name specific alternatives like brain_set_note, but the context is clear.

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

• brain_get_thoughtA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It indirectly signals non-destructive behavior by framing the call as a pre-change understanding step and adds a specific behavioral note about includeSiblings being off by default due to potentially large result sets. It does not explicitly state 'read-only' or error handling, but the key context is present.

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

  Conciseness5/5

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

  The description is two sentences long, front-loading the core function and then providing usage context. Every word earns its place with no fluff or repetition.

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

  Completeness4/5

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

  Given there is no output schema, the description effectively enumerates the return fields (note, parents, children, jumps, tags, type, attachments), which covers the essential return shape. It also hints at potential large sibling sets. It lacks error-case details but is otherwise complete for a read tool.

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

  Parameters3/5

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

  Schema coverage is 100%, and each parameter has a descriptive role, including the helpful 'Take it from brain_list — never guess it' for brainId. The description adds no extra parameter detail beyond the schema, so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool retrieves a full thought including note, parents, children, jumps, tags, type, and attachments in a single call. It also positions itself as the primary means to understand a thought's context, distinguishing it from sibling tools like brain_search or brain_traverse.

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

  Usage Guidelines4/5

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

  The description provides clear guidance on when to use the tool: 'Call it when you need to know what a thought is about and how it connects, before changing or extending it.' This implies a read-before-write pattern but does not explicitly name alternative tools or exclusion criteria, so it stops short of full usage differentiation.

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

• brain_traverseA
  4.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description must convey behavioral traits. It implies a read-only 'walk/view' operation and describes multi-hop behavior, but it does not explicitly state that it makes no modifications, mentions no permissions or side effects, and does not describe return format or performance costs.

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

  Conciseness5/5

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

  The description is three sentences, front-loaded with the primary action, then usage guidance, then a contrast. Every sentence earns its place; no filler or redundancy.

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

  Completeness4/5

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

  The purpose and usage are clear, and all parameters are documented in the schema. However, with no output schema, the description remains vague about what the tool actually returns; 'whole neighbourhood' is evocative but not precise about the data shape, which is a notable gap for an agent invoking it.

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

  Parameters3/5

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

  The input schema has 100% parameter description coverage, so the baseline is 3. The tool description does not add parameter details, but the schema already sufficiently explains depth, follow, maxNodes, and the identifiers, so no extra compensation is needed.

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

  Purpose5/5

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

  The description clearly states the tool's function: it walks the graph plusieurs hops out from a thought, making it a traversal tool. It distinguishes itself from siblings by contrasting 'viewing a thought shows one hop only', so the agent knows this tool is for multi-hop exploration.

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

  Usage Guidelines5/5

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

  It explicitly instructs 'Call it when you need to see the whole neighbourhood', providing a clear when-to-use directive. It also contrasts with the single-hop viewing alternative, giving a practical exclusion and implicit alternative.

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

• brain_indexA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description must disclose behavior itself. It does mention a performance caveat ('The first build on a large brain takes minutes'), implies that rebuild is a full rebuild and sync is incremental, and indicates status is a read-only check. However, it does not explicitly state that rebuild destroys the existing index or that actions may have side effects (e.g., resource usage). The transparency is good but not exhaustive.

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

  Conciseness5/5

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

  The description is three concise sentences, front-loaded with the tool's purpose and then giving actionable usage guidance. There is no filler; every sentence earns its place. It is appropriately sized for a two-parameter tool.

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

  Completeness4/5

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

  For a tool with two parameters, an enum, and no output schema, the description covers the key contexts: when to use each action, what they do, and timing expectations. It lacks mention of return values, but that is not critical for a management tool. The description is nearly complete for an agent to select and invoke it correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%: both action and brainId are already described in the schema (action enum values and 'never guess it' for brainId). The description adds context for when to use each action but does not provide new parameter-level semantics beyond what the schema already offers. Baseline 3 is appropriate here since the schema carries the parameter burden.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Manages the semantic index: status, build, refresh.' It uses a specific verb ('manages') and resource ('semantic index'), and immediately lists the three supported actions, distinguishing it from any sibling tool that does not manage the index. This is a precise, high-clarity purpose statement.

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

  Usage Guidelines5/5

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

  The description provides explicit usage scenarios for each action: 'Call with action=status when brain_search complains the index is missing; with action=rebuild to build it for the first time or after changing the model; with action=sync to pull in changes (fast, new material only).' It also warns about build duration on large brains. This is exemplary when-to-use guidance, though it doesn't contrast with alternative tools since none exist for this specific task.

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

• brain_set_noteA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of disclosure. It explicitly warns 'previous text is lost,' highlighting the destructive nature. It also advises reading the existing note first, which is useful safety context. However, it doesn't mention behavior for nonexistent thoughts or return values, leaving some gaps.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary action, and every sentence earns its place: the replacement semantics, the alternative tool, and a safety caution. No waste.

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

  Completeness4/5

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

  For a simple setter with three parameters and no output schema, the description covers purpose, usage, and the key destructive behavior. It omits details like return values or handling of nonexistent thoughts, but these are less critical for this tool. Overall quite complete.

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

  Parameters3/5

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

  The schema already describes brainId and markdown, with thoughtId lacking a description. The description adds little parameter-specific detail beyond reinforcing that markdown is the complete replacement. With 67% schema coverage, this is adequate but not enhanced.

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

  Purpose5/5

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

  The description states the tool 'Replaces a thought's note entirely.' This is a specific verb+resource combination that clearly distinguishes it from siblings like brain_append_note, which adds rather than replaces.

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

  Usage Guidelines5/5

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

  The description explicitly says 'to add rather than replace, call brain_append_note' and advises reading the existing note with brain_get_thought before overwriting. This provides clear when-to-use guidance and names alternatives.

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

• brain_update_thoughtA
  4.4/5.0
  Behavior4/5

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

  With no annotations present, the description carries the burden and does add useful context by clarifying that only the thought's own properties are modified and the note is untouched. However, it does not disclose whether the update is partial (only provided fields) or full, nor any error/return behavior, which would be relevant for a mutation without annotations.

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

  Conciseness5/5

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

  The description is three short sentences, each earning its place: purpose, use case, and exclusion/alternative. It is front-loaded with the core action and avoids redundancy.

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

  Completeness4/5

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

  Given the tool has 7 parameters and no output schema, the description provides enough to select and invoke correctly, and it even points to alternatives for note editing. It lacks explicit partial-update semantics, but the schema descriptions cover null-clearing behavior. Overall it is sufficient without over-explaining.

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

  Parameters3/5

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

  The schema covers all 7 parameters with descriptions such as 'New title' and 'Caption; null clears it.' The description's mention of 'title, caption, type, colours' is a high-level summary that doesn't map directly to the property names 'name' and 'label', but the schema already disambiguates. Baseline 3 is appropriate since schema coverage is 100%.

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

  Purpose5/5

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

  The description opens with a specific verb ('Changes') and identifies the resource ('a thought's properties'), explicitly listing which properties are affected (title, caption, type, colours). It further distinguishes itself from sibling note-editing tools by clarifying it does not touch the note, which clearly separates it from brain_set_note and brain_append_note.

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

  Usage Guidelines5/5

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

  It gives explicit use cases: 'Call it to rename or reclassify.' It also provides an explicit exclusion and alternative: 'It does not touch the note — use brain_set_note or brain_append_note for that.' This satisfies the when/when-not/alternatives requirement.

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

• brain_list_types_and_tagsA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden. It implicitly indicates a read operation by saying 'list' and provides a rationale for use. While it doesn't spell out 'read-only' or side-effect-free behavior, the phrasing is clear enough to imply no mutation.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the purpose, and a clear directive. Every word earns its place; no fluff or redundancy.

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

  Completeness5/5

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

  Given it has a single well-documented parameter, no output schema, and no nested objects, the description fully covers what the tool does, when to use it, and why. It is complete for its simplicity.

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

  Parameters4/5

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

  Schema coverage is 100% and the parameter description 'Take it from brain_list — never guess it' is already excellent. The tool description reinforces the meaning by referring to 'this brain,' adding context on how the brainId parameter selects the vocabulary. Slight extra value from the description.

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

  Purpose5/5

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

  The description clearly states it lists thought types and tags ('which thought types and tags exist') and frames it as the brain's vocabulary. This is a specific verb+resource combination that distinguishes it from siblings like brain_create_thought or brain_search.

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

  Usage Guidelines4/5

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

  Explicitly instructs to call this tool 'before creating thoughts' to follow established conventions. This gives a clear usage context, but it does not mention alternatives or explicit when-not scenarios, so it falls just short of a 5.

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

• brain_create_thoughtA
  4.6/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses a critical behavioral consequence: 'Always supply parentId — a thought with no links gets lost in the graph.' This warns about orphaned thoughts, which is beyond the schema's 'Without this the thought is left orphaned.' It does not mention return values or failure modes, but the core mutation behavior 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.

  Conciseness5/5

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

  The description is four short sentences, each earning its place: purpose, when-to-use, critical warning, and pre-check advice. It is front-loaded with the verb and resource, with no redundant wording.

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

  Completeness4/5

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

  For a tool with 8 parameters, no annotations, and no output schema, the description is quite complete. It covers when to use, the essential parentId caveat, and the search-first behavior. It does not explain return values, but the schema is rich enough that this is not a significant gap.

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

  Parameters4/5

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

  Schema description coverage is 100%, so baseline is 3. The description adds extra semantic value by elevating parentId to 'Always supply' even though schema marks it not required, and by contextualizing the search-first workflow for tagIds/typeId. This goes beyond the schema descriptions.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Creates a thought and sets its note, type and tags in the same call.' It distinguishes from siblings like brain_update_thought (which modifies existing thoughts) and brain_set_note (which only sets a note) by emphasizing the 'same call' combined operation.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance: 'Call it when adding something new' and 'Search first: a suitable thought may already exist, in which case extending it is the better move.' This tells the agent when to use this tool versus alternatives like updating an existing thought, and implies using brain_search first.

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

• brain_searchA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses a key behavioral trait: 'if the semantic index is not built they are all that works', revealing a dependency on the index and a fallback limitation. It also notes that variants 'raise recall noticeably', providing insight into search behavior. However, it could add detail on result ranking or pagination, but the core behavioral trait is covered.

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

  Conciseness5/5

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

  The description is compact—three sentences—with the core purpose front-loaded. Each sentence adds distinct value: purpose, usage context, and behavioral instruction. There is no redundancy or filler.

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

  Completeness4/5

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

  Given no output schema and 5 parameters, the description provides the essential context for a search tool: what it does, when to use it, and a critical caveat about the index. It also references usage of variants as a prerequisite for best results. The limit and includeAuxiliary parameters are documented in the schema, so the description need not repeat them. Slight lack of return-format detail is acceptable without an output schema.

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

  Parameters4/5

  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 value beyond the schema by explaining the purpose and composition of variants: 'several phrasings of the same concept (synonyms, translation, a broader and a narrower term)' and their impact ('raise recall noticeably'). This enriches the schema's parameter descriptions.

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

  Purpose5/5

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

  The description opens with 'Finds thoughts by meaning', a specific verb+resource statement. It further distinguishes itself by contrasting with exact title lookup ('rather than exact title'), which clearly separates it from siblings like brain_get_thought.

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

  Usage Guidelines5/5

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

  The description explicitly states when to call it: 'Call it when looking for something by description rather than exact title' and gives a concrete example ('check whether a thought on this topic already exists'). It also provides directive usage guidance: 'Always pass variants' with explanation, making the usage context very clear.

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

• brain_delete_thoughtA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden: it discloses permanence, no undo, cascading deletion of note and links, and the need for human confirmation. This is strong behavioral transparency for a destructive tool.

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

  Conciseness5/5

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

  Two succinct sentences front-load the destructive action and include all critical caveats—no undo, human confirmation, and usage restriction—with zero filler.

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

  Completeness5/5

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

  For a destructive delete tool with no output schema, the description covers scope, irreversibility, confirmation requirement, and appropriate invocation context. It is complete for safe and correct use.

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

  Parameters3/5

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

  Schema coverage is 67%, and the schema already describes brainId and confirm well. The description does not add parameter-specific meaning, and thoughtId remains undocumented, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states 'Permanently deletes a thought along with its note and links,' using a specific verb and resource. This distinguishes it from sibling tools like brain_update_thought or brain_get_thought.

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

  Usage Guidelines5/5

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

  Explicitly says 'Do not call it to tidy up on your own initiative — only when the user explicitly asked for a deletion,' giving clear when-to-use and when-not-to-use guidance. It also underscores required human confirmation.

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

• brain_listA
  4.7/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the output content (brains, current open, semantic index readiness) and implies a read-only operation via verbs like 'lists' and 'shows.' It doesn't explicitly state side-effect-freeness, but the nature of the operation makes it clear.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core action, followed by usage guidance and an additional output detail. Every sentence earns its place; there is no filler or redundancy.

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

  Completeness5/5

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

  For a zero-parameter tool with no output schema, the description provides sufficient context: what it lists, why to call it first, and what additional state it reveals. It is complete for guiding an agent's initial action and integrates well with the sibling tool set.

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

  Parameters4/5

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

  The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific information, but none is needed because the schema is empty and fully covered.

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

  Purpose5/5

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

  The description states a specific verb and resource: 'Lists the user's brains and which one is currently open in the app.' This clearly distinguishes it from siblings like brain_list_types_and_tags by focusing on the brains themselves and the open state.

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

  Usage Guidelines5/5

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

  It explicitly says 'Call this first in any session' and explains why: 'every other tool needs a brainId and guessing one is not allowed.' This gives clear when-to-use guidance and positions the tool as the required entry point.

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

• brain_ingestA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the tempId mechanism ('the server substitutes real identifiers'), how a parent can be a tempId or an existing UUID ('how a new branch grafts onto what the brain already holds'), and the schema adds deduplication-on-by-default (making re-runs safe), order independence, and maxItems 200. These are non-obvious behaviors an agent must know.

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

  Conciseness5/5

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

  The description is three tightly scoped paragraphs: the first states purpose and when to use, the second explains the tempId/parent mechanism, and the third offers search-first guidance. Every sentence earns its place—there is no repetition of schema details or filler. The front-loaded verb and resource make the tool's purpose immediately clear.

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

  Completeness5/5

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

  Given the tool's complexity (bulk write with tempIds, links, tags, deduplication, and no output schema), the description provides complete context for selection and invocation. It covers the purpose, prerequisites (brainId from brain_list is stated in the schema), the tempId workflow, the deduplication safety, and the recommended search-first sequence. No essential guidance is missing.

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

  Parameters5/5

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

  Schema coverage is 100%, but the description adds substantial meaning beyond the schema. For example, it defines tempId as 'arbitrary labels you invent yourself', explains the parent field's dual nature (tempId or existing UUID) in the context of grafting, and clarifies that links are 'extra links on top of the hierarchy.' The deduplicate parameter's default behavior is also described, enabling correct invocation choices.

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

  Purpose5/5

  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: 'Writes a whole structure of thoughts, links, notes and tags in a single call.' It clearly distinguishes itself from the one-by-one siblings by emphasizing batch scope and explicitly contrasts with creating thoughts individually ('creating them one by one at that volume is slow and breaks halfway'). This leaves no ambiguity about what the tool does.

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

  Usage Guidelines5/5

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

  It gives explicit when-to-use guidance: 'Call it once you have decomposed some material...' and warns against using the alternative (one-by-one creation). It also provides a concrete 'search first' rule: 'Search with brain_search first: some of the thoughts may already exist, and linking to them beats creating duplicates.' This names the alternative tool and states the precondition.

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