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

The annotations already establish read-only, idempotent, non-destructive behavior, but the description adds useful context beyond them: it is cheap, the server auto-starts on first use, and a healthy answer confirms readiness. It also lists the returned fields, compensating for the lack of an 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?

The description is three sentences and front-loads the purpose, then the returned data, then the usage guidance. Every sentence adds useful information without 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 health-check tool with no output schema, the description covers what the tool does, what it returns, when to use it, and what a healthy result means. Nothing critical is missing for correct invocation.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the empty schema is fully consistent with a health-check 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 description states a specific verb and resource: 'Check that the Second Brain server is running' and get vault statistics. It also names the exact statistics returned (status, version, nodeCount, edgeCount), making clear this is a health/status tool rather than a data 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 explicitly says when to call it: first if another tool fails with a connection error, or to confirm the memory is connected. It also explains that the server starts automatically on the first tool call, so a healthy response means everything is ready.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint false, and openWorldHint false. The description adds meaningful context beyond those annotations: reading does not mark messages as read, all matching messages are returned at once with no pagination or guaranteed order, and a count of 0 means an empty inbox. It does not discuss access permissions, but for a read-only inbox tool the additional behavioral context is substantial.

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

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

The description is dense and front-loaded: scope, read-only behavior, follow-up tool, pagination/order caveat, return shape, and empty-inbox meaning. Every sentence carries actionable information without unnecessary wording.

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?

Although there is no output schema, the description provides the full return shape, clarifies that results are unpaginated and unordered, and explains what count 0 means. Combined with the annotations, this is complete enough for an agent to call and interpret the tool correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description restates that unread defaults to true and false returns the full history, but adds little parameter-specific meaning beyond the schema; its extra value is in overall return behavior rather than parameter semantics.

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

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

The description states a specific verb and resource: read messages addressed to an agent. It immediately clarifies the default unread scope versus full history, which cleanly distinguishes this inbox-reading tool from sibling tools like brain_messages_mark_read and brain_messages_send.

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

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

It explicitly explains when to use the default unread view versus unread=false for full history. It also names the follow-up tool, brain_messages_mark_read, and specifies that reading does not mark messages as read, giving the agent a clear workflow.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds substance beyond them: the message stays in the vault and in full history, so the state change is scoped to inbox visibility only. It also discloses the return contract ({ success: true, id }) and the exact error case ('Message not found' for an unknown id or non-message note).

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

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

Four short sentences, front-loaded with the effect and followed by the trigger, idempotency guarantee, and return contract. No sentence is filler; each adds a distinct fact an agent needs.

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

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

For a one-parameter mutation tool with annotations and no output schema, the description covers trigger, durability of the change, repeat-safety, return shape, and failure mode. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already specifies that the id comes from brain_messages_get with an example format, so the description adds no new parameter detail. Baseline 3 applies when the schema carries the parameter semantics.

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 ('Mark one message as read') plus the observable effect: it disappears from the default unread inbox returned by brain_messages_get. That explicit link to the sibling tool lets an agent distinguish it from brain_messages_get or brain_messages_send 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?

'Call it after you have handled a message' gives a clear trigger condition, which implicitly excludes marking messages as read before processing them. It stops short of naming alternatives or an explicit when-not, but for a single-purpose one-parameter tool the guidance is actionable.

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 write, non-idempotent, non-destructive, closed-world, so the description adds genuinely new behavior: nothing is delivered in real time, unknown recipient names are accepted and silently create a new inbox, malformed names are rejected with a reason, and duplicate sends duplicate the message. It also documents the return shape ({ success, id }) despite no output schema existing. It does not discuss message size limits or retention/deletion of inbox contents, so it is strong 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.

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

Sentences are dense and ordered usefully: purpose, consumption path, when-to-use, delivery semantics, recipient-name caveats, duplicate behavior, return value. No filler, though the recipient-name caveat is spread across two sentences that could be merged.

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 four-parameter write tool with no output schema, the description covers everything an agent needs: when to use it, that delivery is asynchronous, that names are unvalidated, that sends are not idempotent, and what the response contains. No significant decision-relevant gap remains.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds practical meaning by framing toAgent as a free-form name that will not be validated against existing agents ('check the spelling') and by explaining the failure mode for invalid characters. It adds little beyond the schema for content, subject, and fromAgent defaults, which the schema already states.

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 opening sentence states a specific verb and resource ('Send a message to another agent's inbox') and immediately ties it to the sibling tools that consume the message (brain_messages_get, brain_messages_mark_read), so the agent can position it in the workflow without opening a schema.

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

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

It gives an explicit inclusion criterion ('short hand-off context that does not belong in a task or a permanent note'), which implicitly routes task-shaped or durable content to brain_tasks_submit or brain_remember, and it explains the delivery model (recipient must check its inbox) that determines whether this tool is even 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 readOnly, idempotent, non-destructive and closed-world, so the "Read-only" sentence is largely redundant. What the description does add beyond the structured data is real: the warning that a large note produces a large response, and the disclosure that an unknown id yields a "not found" error rather than an empty result.

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

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

Four short sentences, front-loaded with the return shape before the usage guidance. Minor waste exists in restating "Read-only" which the annotations already cover, but nothing else is padding.

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

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

With no output schema, the description must describe return values and it does so field by field, plus adds the error case and the size caveat. For a single-parameter read tool, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% and the id property already explains the exact format and its origin from brain_search/brain_recall/brain_remember. The description only says "by id", adding no new meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource ("Fetch one note by id") and immediately enumerates what comes back: markdown content, metadata fields, outLinks and inLinks. An agent can distinguish it from brain_search and brain_recall without opening any schema, since those return collections rather than a single fully-expanded 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?

It gives two concrete use cases with the alternative named in each: read in full before overwriting via brain_node_update, or follow a link discovered in recalled context (versus brain_recall). The relationship to sibling tools is explicit rather than inferred.

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

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

Goes well beyond the annotations, which only flag destructive/non-idempotent/non-read-only. The description spells out exactly what gets destroyed in replace mode, that tags and importance overwrite rather than merge, the optimistic-concurrency check with a single automatic retry, the return shape, three named error conditions, and that no credentials are needed when BRAIN_KEY is set. Nothing here contradicts destructiveHint=true or idempotentHint=false.

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

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

Front-loaded with the core distinction (update in place vs. duplicate) and then ordered by decision-relevance: mode semantics, overwrite rules, concurrency, return value, errors. Dense but a few clauses, particularly the credentials sentence, could be trimmed without loss.

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 5-parameter mutation with no output schema, the description covers everything an agent needs: mode choice, overwrite/merge behavior, concurrency and retry, response shape, error taxonomy with recovery, and auth expectations. No meaningful gap remains for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value by tying mode to content (append vs. full-body replace), clarifying that tags/importance replace rather than merge, and noting that passing only an id yields "Nothing to update". Most of the per-parameter meaning, however, is already carried by the schema descriptions, so it edges just above baseline rather than redefining semantics.

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?

"Update an existing note in place instead of creating a near-duplicate" states the verb, the resource, and the failure mode it exists to prevent, which cleanly separates it from the sibling brain_remember (create). It also names brain_node_get as the read counterpart, so the agent can place the tool in a workflow 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?

Explicit routing guidance: default append for adding text, replace only when you have the full corrected body and have read it with brain_node_get first. It also states the alternative (creating a near-duplicate is what this avoids) and the recovery path on conflict (read again and retry).

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the matching strategy, that hop expansion traverses [[wikilinks]], that results are packed under a token budget with overflow dropped, and the full return shape. The note that systemPrompt marks notes as reference data rather than instructions is a meaningful trust-boundary disclosure an agent cannot infer from structured fields.

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

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

Front-loaded with purpose and effect, then usage guidance, then return shape, then the disambiguation sentence. Nearly every clause carries information, though the mechanism clause and the return-value enumeration make it denser than strictly necessary.

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

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

No output schema exists, and the description compensates by naming the returned fields and explaining the role of the key one (systemPrompt as a ready-to-use, reference-marked context block). For a three-parameter read tool with a non-obvious retrieval pipeline, 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?

Schema coverage is 100%, so the baseline is 3, but the description adds pipeline-level meaning: it explains what hops actually do (follow wikilinks outward from matches) and what maxTokens controls (the packing budget, with omissions when exceeded). It stops short of restating defaults or caps, which the schema already handles.

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 ("Recall relevant memory for a query from the shared Second Brain vault") and then describes the retrieval pipeline: keyword/recency matching, optional semantic similarity, wikilink expansion, token packing. It explicitly names the sibling it is not (brain_search) and the condition that distinguishes 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?

Gives an explicit trigger ("Call this before answering anything that earlier work may already cover: past decisions, constraints, research, project background") plus a named alternative and the exact condition for choosing it ("Use brain_search instead when you only need a ranked list of matching notes"). Both when-to-use and when-to-use-something-else 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 a non-read-only, non-destructive, non-idempotent mutation; the description adds real value on top by confirming it never overwrites (title clashes get a numbered filename), disclosing the return shape { success, id, title, type, version }, and warning that notes are plain files that may be synced to git so secrets must be excluded. The only minor gap is that it does not mention any permission or auth requirement before writing.

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

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

Purpose is front-loaded in the first sentence, then gating criteria, then the alternative-path instruction, then behavioral/return details. The length is justified by the amount of decision-relevant content and the "Test:" framing keeps the qualification crisp rather than rambling.

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

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

A mutation tool with no output schema, yet the description compensates by stating the exact return fields and advising the agent to retain the id for later reference. Combined with the no-overwrite behavior, the duplicate-avoidance workflow, and the secrets warning, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so tags, type, agent, title, content and importance are all fully documented in the schema already, which sets the baseline at 3. The description adds only marginal parameter meaning — that a title clash yields a numbered filename — and does not explain importance or type trade-offs beyond what the schema states.

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 ("Write a new memory/research note into the shared Second Brain vault") plus the downstream purpose (recall in future sessions or other projects). It distinguishes itself from siblings by naming brain_search and brain_node_update as the preferred path for existing 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?

Gives explicit inclusion criteria (genuine reusable learning: fact, pattern, constraint, decision), explicit exclusions (routine task completions, raw output, status updates — pointing at the task queue), and a concrete self-test question. It also routes to alternatives: search first, then update an existing note rather than duplicating.

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 behavior beyond the readOnly/idempotent annotations: hybrid keyword+semantic matching, recency re-ranking, and that an empty list means no match. "Read-only" merely repeats the annotation, and ordering/pagination behavior under the limit is not elaborated, so it stops 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?

Front-loads the search mechanism, then routing, then return shape in a logical order with no filler. The standalone "Read-only." sentence duplicates the annotations and could be dropped, which keeps it from a 5.

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

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

There is no output schema, and the description compensates by spelling out the returned object shape and the meaning of an empty result. Combined with explicit routing to siblings, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description only reinforces that the query matches titles, tags, and content, and adds no syntax or format detail for limit beyond the default already in the schema.

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

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

States a specific verb and resource ("Search the vault for notes") plus the exact matching mechanism (keyword over titles/tags/content, semantic similarity when embeddings are configured, recency re-ranking). It distinguishes itself from brain_recall, brain_remember and brain_node_get, which are named directly.

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

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

Gives explicit when-to-use cases (check for an existing note before brain_remember, obtain a note id for brain_node_get / brain_node_update) and names the alternative brain_recall with the condition that selects it (assembled context to answer a question).

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds what they cannot say: no pagination, no guaranteed order, an empty list means no matches, and 'content' holds the prompt and any partial result. That is behavior an agent needs and cannot get from structured fields.

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

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

Scope and filter come first, then return shape, then sibling routing. Every sentence carries distinct information and nothing is repeated from the schema verbatim.

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 available, the description supplies the response shape inline (count, tasks with id/title/tags/content/createdAt) and clarifies that 'id' is the key brain_tasks_update expects, leaving no call-shaping ambiguity.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning by explaining what the 'pending' and 'blocked' enum values imply for the caller's workflow rather than just restating the enum.

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

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

States a specific verb and resource ('List the tasks in the shared queue') plus an optional filter, and explicitly separates itself from brain_tasks_submit and brain_tasks_update by function.

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

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

Gives concrete when-to-use guidance tied to filter values ('pending' to find work waiting for you, 'blocked' to see what is waiting on dependencies) and points to the sibling tools for adding tasks or changing state.

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

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

Annotations declare the mutation profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the description is not required to restate safety, but it does add real behavior: dependency-driven initial status, automatic transition from blocked to pending, and a concrete return shape { taskId, nodeId, status } in the absence of an output schema. It stops short of stating whether duplicate submissions create duplicates, which is the one behavior an agent still has to guess given idempotentHint=false.

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

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

Four sentences, each doing distinct work: purpose, status lifecycle, the not-a-runner constraint with named alternatives, and the return value plus prompt-authoring advice. The scoping constraint is front-loaded and nothing is redundant.

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

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

For a create tool with no output schema, the description covers the mutation's effect, the status lifecycle, the return shape, and the division of labor with sibling tools. An agent has everything needed to submit a well-formed task and to know what to do next.

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

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

Schema coverage is 100%, so the schema already documents all five parameters and a baseline of 3 applies. The description adds meaning beyond it by telling the agent how to compose the required prompt (goal, relevant files, constraints, definition of done) and by framing dependencies as nodeId values from earlier submits, which reinforces the schema rather than merely repeating it.

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

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

The description opens with a specific verb and resource ("Add a task to the shared, markdown-backed task queue") and immediately names the purpose (another agent or later session can pick it up). It explicitly distinguishes itself from the sibling tools brain_tasks_list and brain_tasks_update, so an agent can separate recording from watching and reporting.

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 states the key boundary explicitly: "This only records the task: it is a coordination list, not a runner," and names what must handle the rest (brain_tasks_list to watch, brain_tasks_update to report back). It also gives authoring guidance for the required prompt field, so the when and how are both covered.

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

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

Beyond the annotations, it discloses the dependency cascade (dependents become "pending" on completion, "failed" if a dependency failed or was cancelled), that the result text replaces any earlier result while prompt and sub-results are kept, and the exact error string for an unknown id. It also confirms idempotency, consistent with idempotentHint=true. The only slight gap is that it doesn't discuss authorization or concurrency, which are likely non-issues here.

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

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

The core action and status intents are front-loaded, followed by side effects, return shape, errors, and sibling routing in a logical order. Every sentence carries information, though the dependency-cascade sentence is dense enough that a slight trim would improve scanability.

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

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

Even without an output schema, the description specifies the return fields ({ success, id, status, releasedDependents }) and their meaning, plus the failure mode. For a three-parameter mutation tool this leaves nothing important unexplained.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that `result` overwrites the Final Result section while preserving the prompt and sub-results, and that omitting it changes status only. The status enum is also given intent-level semantics rather than left as a bare list.

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

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

The description opens with a specific verb and resource ("Change the status of a task and, optionally, record its outcome") and enumerates the concrete transitions it performs. It is clearly separable from siblings, which are named for their distinct roles (brain_tasks_list for ids, brain_tasks_submit for creation).

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 states exactly which status value corresponds to which intent ("running" to claim, "completed"/"failed" to finish, "cancelled" to withdraw) and routes the agent to brain_tasks_list for ids and brain_tasks_submit for creation. There is no ambiguity about when this tool is the right choice.

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