Brainz

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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral detail: it sets taskStatus=done and doneAt, appends the outcome to the body as an Outcome section, and notes a reminder that the rest of the graph is not updated. It doesn't mention permission requirements or irreversibility, but the added 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?

Three sentences with zero waste, front-loading the core action and following with precise side effects and a caveat. Every sentence earns its place.

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

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

For a simple two-parameter mutation with no output schema, the description covers what is changed, how the outcome is stored, and a behavioral reminder. It lacks error-case or return-value elaboration, but given the annotations and rich schema, it is largely complete.

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

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

Schema coverage is 100%, so both parameters are already documented. The description mostly repeats the schema's explanation of `outcome` without adding new syntax, format, or constraints, and says nothing extra about `id`. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb ('Mark done') and resource ('task'), and details the exact mutations performed. It does not explicitly differentiate from sibling tools like take_task or create_task, but the purpose is unambiguous.

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

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

Usage is implied by the clear purpose: use when you want to complete a task. However, there are no explicit when/when-not conditions, prerequisites, or named alternatives, leaving the agent to infer context.

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

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

Annotations already declare a non-destructive write, so the description's added value is the default state (taskStatus=open), the edge side effects from relations and body wiki-links, and the fact the task surfaces on the Kanban board and in list_tasks. It does not address duplicate detection or whether a failed relation id aborts the whole creation, which are the remaining meaningful unknowns for a mutation.

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

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

Two sentences, front-loaded with the outcome before the usage trigger and the downstream visibility note. The mid-sentence relation list is dense but every clause carries information; nothing is padding.

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

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

With 7 parameters, 100% schema coverage, and non-destructive write annotations, the description covers the trigger, the created object's shape, the relation semantics, and the downstream effects. It omits what the call returns (the created task's id?) — tolerable given no output schema, but an agent assembling a follow-up call would benefit from it.

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 every parameter is already documented in the schema. The description reframes the relation fields conceptually (part_of a domain, realizes stories/features, governed_by specs, codeAreas as landing paths) but adds little syntax or constraint detail beyond the schema — the correct baseline 3.

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: creates a `task`-type concept with taskStatus=open, plus the relations (domain, realizes, governed_by, codeAreas) it wires up. It clarifies downstream visibility in list_tasks/take_task, but never contrasts itself with the sibling that could also create concepts (upsert_concept), so sibling differentiation is implied rather than explicit.

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

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

"Use when you discover work that isn't reflected in the codebase yet (a gap, a needed fix, a follow-up)" gives a concrete trigger condition with examples. It stops short of exclusions — nothing says when to prefer upsert_concept or take_task instead — so it is clear context without alternatives.

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

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

Annotations already declare destructiveHint=true, and the description adds substantial context beyond them: cascading deletion of outgoing edges, idempotency (deleting a missing id returns deleted:false rather than erroring), and that deletion is permanent. Also discloses the return shape, none of which appears in the 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?

Five short sentences, each carrying distinct information – side effect, when to use, idempotency, permanence, return value – with no repetition. The core action and cascade behavior are front-loaded before the caveats.

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 one-parameter tool with no output schema, the description covers everything an agent needs: what gets removed alongside the concept, that the operation is permanent and idempotent, and what the response contains. No meaningful 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% and the single id parameter is already fully documented including an example, so the description doesn't need to re-describe it. It only adds a behavioral note about ids that don't exist, which is more about idempotency than parameter meaning; baseline 3 applies.

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

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

States a specific verb and resource plus the side effect ('remove a concept ... and all of its outgoing edges'), which tells the agent exactly what the operation touches. It is clearly distinguishable from upsert_concept, the only sibling that writes concepts.

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 when-to-use case (wrong, obsolete, or junk notes such as test/probe nodes) and names the alternative for the opposite case: prefer upsert_concept to correct a note you want to keep. The exclusion plus named alternative is exactly what routing needs.

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 destructiveHint=true annotation by naming exactly what is destroyed and how: duplicate merges redirect edges and tombstone the loser, outcomes are promoted, contradictions become tasks. It discloses safety behavior the annotations cannot: threshold gates reject sweeps that touch too much, and every applied dream keeps preimages and can be reverted.

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

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

Front-loaded with the core purpose and staged behavior, then the action map, with no filler. The action sentence is long and packed but each clause carries distinct operational meaning; a slightly tighter structure would earn 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?

For a complex, destructive, open-world mutation tool with no output schema, the description covers the pipeline, thresholds, LLM dependency, rejection behavior, and reversibility. An agent has enough context to call all five actions safely without needing return-value documentation.

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

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

Schema description coverage is 100%, so all five parameters and the action enum are already fully documented in the schema. The description restates the action semantics (status/run/diary/revert/configure) but adds no syntax, defaults, or constraints beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource: a scheduled consolidation sweep over the vault, broken into light, REM, and deep stages. It is unmistakably distinct from every sibling (no other tool performs consolidation or dreaming), so an agent can identify it without opening the schema.

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

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

The description routes each action clearly: status for schedule/state, run to dream now, diary to read entries, revert with id to undo, configure to enable/cadence. It also notes that without an LLM only light runs, which is a real usage constraint. It does not explicitly say when to prefer this over manual curation via siblings, but the tool is unique enough that this is a minor gap.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint false, openWorldHint false), so the remaining burden is explaining what a call yields. The description does that well by naming the three payload parts and the fact that each neighbor carries its relation. It stops short of saying anything about missing-id behavior or error semantics.

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?

Opens with the core fetch semantics and return shape, then layers usage routing; nearly every clause earns its place. The closing 'use search_concepts instead' slightly repeats the earlier 'use after search_concepts' framing, a minor redundancy rather than 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?

There is no output schema, so describing return values is mandatory here and the description does it precisely. Combined with annotations covering safety, an agent has everything needed to decide to call it and what to expect afterward.

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

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

With 100% schema description coverage and a single required parameter, the schema already defines the id format and gives an example slug. The description reinforces exact-match lookup, but adds no new syntax or constraint details beyond what is structured. Baseline 3 applies.

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

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

States a specific verb+resource (fetch one concept by exact id) and immediately enumerates what comes back: full markdown body, metadata, and direct graph neighbors with their connecting relation. It is clearly distinguished from the sibling search_concepts, which returns the ids this tool consumes.

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 entry conditions ('Use after search_concepts or when another note wiki-links an id') and an explicit exclusion with the alternative ('If you don't know the id, use search_concepts instead'). It also explains how to continue work ('the neighbors list tells you what to fetch next'), which no sibling tool description could supply.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely new behavior: the output is a self-contained markdown briefing, it may be truncated to a token budget, and a final JSON line reports included ids, truncation status, and token count. Missing only details like ranking behavior or what happens when the budget is too small to fit even seeds.

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

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

Four tight sentences, front-loaded with the core action and artifact, followed by output-format details and the input constraint. Every sentence carries information an agent needs; no filler.

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

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

With no output schema, the description steps up to explain the return shape (self-contained markdown plus a final JSON line with ids/truncated/token count) and the invocation constraint. Together with annotations covering safety and the schema covering parameters, 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 baseline is 3; the description adds value beyond the schema by stating the cross-parameter constraint that at least one of `query` or `ids` must be supplied — a requirement not encoded in the schema (required: []). It does not further explain depth, product, or tokenBudget semantics beyond the schema, so it is not a 5.

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 (assemble) and a specific artifact (markdown briefing of concepts expanded through the graph), plus the scoping inputs (query/ids) and the trimming constraint. It is clearly distinguishable from siblings like search_concepts, get_concept, and get_related, which return raw concepts rather than a budgeted bundle.

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

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

Provides a concrete usage context — self-contained briefing to hand to another agent or paste into a prompt — and an explicit input constraint ('Provide at least one of `query` or `ids`'). It does not name sibling alternatives or state when not to use it, so it falls short of a full routing guide.

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 safe, closed-world read, so the description's job is to add traversal behavior, which it does: it discloses the hop limit semantics and exactly what the response carries (distance plus edge path). It doesn't discuss cost or result-size behavior for deeper traversals, which is a minor gap given the depth cap of 3.

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

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

Three sentences, front-loaded with the core action and return value, then usage, then filtering. No filler and no duplication of schema detail.

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 describing what comes back (distance and the edge path that reached each node). With four fully documented parameters and clear annotations, 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 description coverage is 100%, so baseline is 3. The description goes slightly beyond by explaining the intent of the relations filter ("follow only one kind of edge") and framing depth as hops into the graph, adding conceptual meaning rather than repeating types and ranges.

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 ("walk the knowledge graph outward from a concept") and adds scope detail: everything within depth hops, plus the distance and edge path returned. This is clearly distinguishable from get_concept and search_concepts, the latter explicitly contrasted with "keyword search".

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

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

Gives two concrete use cases (mapping blast radius before changing a feature; discovering structure keyword search misses) and a narrowing instruction via relation names. It stops short of naming when to prefer get_concept or search_concepts by tool name, so a little inference is still required.

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

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

The description adds crucial behavioral context by detailing *how* the change is implemented: 'by editing the `from` note's frontmatter.' This mechanical detail is a significant addition beyond the simple 'destructiveHint: false' annotation.

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 extremely concise. It front-loads the core function, provides a live example, and closes with the workflow constraint, maximizing information density without unnecessary 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?

Given the rich schema, annotations, and parameter definitions, the description fills all necessary behavioral and procedural gaps. It tells the agent exactly what, why, and how to use the tool successfully.

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?

Although schema coverage is 100%, the description provides semantic value for the 'relation' parameter by explaining its intent (domain links, overlaps) and giving multiple practical examples of different edge types, which enhances understanding beyond the schema's basic definition.

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

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

The description clearly states the purpose: 'Add a typed, directed edge between two existing concepts.' It provides a concrete, actionable example ('lead-scoring depends_on contact-model') making the intent perfectly clear.

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

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

It provides explicit usage guidelines by stating when the tool should be used (when a relationship is missing) and what prerequisite must be met, specifically directing the agent to use `upsert_concept` if the concepts don't exist.

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

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

Annotations already cover readOnly/non-destructive/no open-world, so the remaining burden is low. The description still adds a meaningful trait the annotations don't: results are metadata only, no bodies. It omits any note on result volume, ordering, or pagination, which matters for a parameterless listing tool.

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

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

Three short sentences, front-loaded with the core action and scope, then usage, then the follow-up path. No redundant restatement of the title or annotations.

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

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

With no output schema, the description does the most important work by stating that only metadata is returned and pointing at get_concept/get_context for bodies. It stops short of describing what metadata fields come back or how large an unfiltered listing may be.

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 nuance beyond the schema by stressing that all filters are optional and that 'tag' accepts only a single tag, which clarifies the filtering 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 ('Enumerate concept metadata') and immediately bounds the scope with '(no bodies)'. The phrase 'when search vocabulary isn't matching' implicitly contrasts it with the search_concepts sibling, so an agent can distinguish listing from searching.

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 three concrete activation scenarios: orientation in an unfamiliar vault, auditing existing artifacts (e.g. all decisions for a product), and failed search matches. It also routes follow-up for content to get_concept/get_context, though it never explicitly says when to prefer search_concepts instead.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral detail beyond those annotations: oldest-first ordering, lifecycle states, and inclusion of takenBy. It does not discuss pagination or result limits, but no pagination parameter exists.

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

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

The definition is compact and front-loaded: it states what is listed, ordering, included information, filtering options, and the read-only distinction from take_task in a single efficient passage.

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

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

For a simple read-only list tool with two optional, fully documented parameters and no output schema, the description gives enough context to invoke it correctly. It covers ordering, lifecycle, included ownership information (takenBy), and filter behavior.

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 optional parameters are already well documented in the schema. The description mentions taskStatus and domain filtering, but adds little syntax or meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description names a specific verb and resource (list tasks), scopes them to the vault's work pile, and explains the lifecycle and included field (takenBy). It also distinguishes the read-only listing behavior from take_task, so an agent can route correctly without opening the schema.

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

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

It states the two filtering modes, taskStatus and domain, and explicitly points to take_task for claiming a task. It does not explicitly compare against list_concepts or search_concepts, but the usage context is clear.

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

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

The description discloses behavior beyond the annotations: complete is conditionally rejected, the summary is stored as a concept, and incomplete onboarding causes a note to appear in search_concepts and get_context results. It also explains why areaList must come from the caller because Brainz cannot read the repo.

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

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

The description is front-loaded with the core purpose and then devotes one dense, purposeful sentence to each action. There is no filler, and the most important workflow effects are placed early.

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 stateful onboarding workflow with no output schema, it explains what each action returns or stores, the rejection condition for completion, and cross-tool side effects. An agent has enough context to choose an action and 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 already 100%, so this is judged on added meaning. The description reinforces conditional parameter combinations, such as areaList being supplied for status and complete and summary being required for complete, and explains the consequence of uncovered areas.

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: 'Index an existing product's codebase into this vault.' It then characterizes the three actions and how onboarding relates to upsert_concept, making the tool's scope clear without needing sibling comparison.

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 precise per-action usage: start returns the playbook, status reports coverage, and complete stores the summary and is rejected when too many areas are uncovered. It does not explicitly compare against alternatives like sync or upsert_concept, but the action-level routing is very clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's added value is in disclosing the return shape (id, title, type, score, snippet) and the meaning of an empty hit list. That is real context beyond the annotations. It stops short of covering result-size behavior at the limit boundary or the fact that ranking can degrade to keyword-only, though the latter is documented in the schema.

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

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

Four sentences, front-loaded with the purpose, then usage, then return contract, then the empty-result edge case. No sentence is filler and nothing important is buried.

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?

Six parameters with full schema coverage and no output schema, so the description must carry return semantics, which it does by naming the five hit fields and explaining the empty list. Combined with explicit sibling routing, an agent has everything needed to call it correctly and interpret the response.

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 each of the six parameters, including the mode enum and its semantic-to-keyword fallback, is documented in the schema. The description adds only the notion of 'free-text query' and says nothing about mode, tags, type, product, or limit, so this is the baseline case where the schema does the work.

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

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

Specific verb ('Search') plus specific resource ('the product knowledge vault') qualified by 'free-text query'. It also names what comes back (ranked hits) and explicitly separates itself from get_concept and get_context, so the agent can choose without opening other schemas.

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

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

The condition is stated directly: use this 'when you need product knowledge but don't yet know which concept ids exist.' It then routes to the two natural alternatives, get_concept for one full note and get_context for an assembled briefing, which is an explicit when/when-not split.

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?

With annotations only covering safety flags, the description carries and delivers the real behavioral burden: the agent must supply repository data because 'Brainz can't read the repo', `complete` mutates last_synced_at and appends (never overwrites) to a concept, `complete` is rejected when coverage gaps are too large, and after ~14 days without a sync get_context and search results gain a staleness note — a cross-tool side effect not visible in annotations.

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

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

Purpose is front-loaded and each sentence maps to a distinct action or consequence, with no filler. It is dense and slightly redundant with the schema's own parameter text (the append behavior and coverage rejection are stated twice), which keeps it short of 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, yet the description tells the agent what each action returns: `start` yields a drift playbook with last_synced_at, a coverage map and a re-index method; `status` yields onboarded state, staleness and counts. Combined with the mutation side effects and the ~14-day staleness consequence, an agent can call this correctly without further context.

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 descriptions already state the git-walk provenance, the append-not-overwrite behavior, and the rejection rule, so the description largely repeats structured data. It does tie the parameters to the workflow ('you run git ... and pass back changedPaths + areaList'), which adds modest value, but the baseline of 3 applies when the schema does the heavy lifting.

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

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

The opening sentence gives a specific verb and resource — 'Re-index an onboarded vault after the code changes (drift)' — and the three action modes (start/status/complete) are each spelled out. The prerequisite ('an onboarded vault') implicitly separates it from the `onboard` sibling, though it never names `onboard` explicitly as the alternative for a first pass; that contrast only appears in the schema.

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

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

Each action has a stated purpose and the description explains the operating sequence: run git yourself, pass back changedPaths + areaList, then call complete to stamp the sync. It doesn't explicitly say when NOT to use it (e.g., for a vault that was never onboarded, or how it relates to `onboard`), so guidance is clear but not exhaustive.

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

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

Annotations only say it is a non-destructive, closed-world mutation; the description goes well beyond that by disclosing atomicity ('atomically flips the task to "taken"'), the exact state written (takenBy/takenAt), and the error case for already-taken/done tasks. It also pre-announces the shape of the payload (task plus a get_context-style briefing with concepts and code_areas), which is exactly what an agent needs before calling a claim tool.

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

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

Four tight sentences, front-loaded with the action, then the two invocation modes, then side effects, then the return payload and the follow-on tool. No sentence is 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?

With no output schema, the description compensates by describing what comes back (the task plus a get_context-style briefing with part_of domain, concepts, code_areas). Combined with the disclosed error conditions and atomicity, nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100% and both parameters are already documented there, including the ordering rule and the takenBy default. The description largely restates the `id` semantics rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Claim a task') plus the bundled side effect ('get its briefing in one call'), which distinguishes it cleanly from list_tasks, create_task and complete_task. An agent can tell what this does without opening the schema.

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

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

Explicitly branches usage: pass an `id` for a specific task, omit it to claim the next open task with a stated ordering (oldest by createdAt then id). It also names the follow-on sibling ('complete_task marks it done') and states the failure condition (already taken or done).

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

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

Adds real context beyond the annotations: the write is an overwrite of a markdown file followed by a reindex, which substantiates the destructiveHint=true flag rather than contradicting it. It also discloses the return shape. A 5 would need to say what an overwrite does to fields not supplied (e.g. are tags/relations cleared), which is the main behavioral risk for an upsert.

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

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

Four tight sentences with the mutation behavior front-loaded and the create-vs-update rule following it; nothing is padding. Minor overlap with schema descriptions 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?

Covers return values verbally since there is no output schema, and handles the create/overwrite distinction for a 13-parameter tool with nested relations. The gap is update semantics: it never says whether an overwrite preserves or drops existing tags, relations, or status.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters, including id derivation and wiki-link semantics. The description restates the id and body behavior without adding syntax or format detail not already present. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource — writes a concept note into the vault — and immediately clarifies the create-or-overwrite semantics plus the reindex side effect. This distinguishes it cleanly from read-side siblings like get_concept and search_concepts, and from the task-specific create_task.

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

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

Gives a concrete when-to-use framing (capture decisions, constraints, patterns discovered during a task) and explains the id-omitted vs id-passed branching for create vs update. It stops short of naming exclusions or deferring explicitly to siblings like create_task or link_concepts, which would be needed for a 5.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds value beyond that by disclosing the return payload's contents — including the non-obvious availability flag for semantic search, which an agent would otherwise have to discover empirically. It does not discuss cost, caching, or freshness, keeping it short of a 5.

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

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

A single sentence, front-loaded with the verb and resource, followed by a compact enumeration of return fields and one clause on usefulness. No filler or repetition of the title.

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

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

With no parameters, no output schema and a simple read-only surface, the description covers what an agent needs: what is counted and what filters can be discovered. Minor gap: no mention of response shape or whether counts are live/approximate, though this is low risk for a stats call.

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

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

Zero parameters, so there is nothing to disambiguate; the baseline for a no-arg tool applies. Nothing in the description is needed or wasted on 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 (summarize) and resource (the vault), then enumerates exactly what the summary contains: concept/edge counts, products, tags, concept-type breakdown, and semantic-search availability. No sibling tool (list_concepts, search_concepts, get_context) produces aggregate statistics, so it is easy to distinguish from the rest of the toolset.

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?

"Useful for gauging how much knowledge is here and which product/tag filters exist" implies a discovery/orientation use case, which is real guidance. But it never says when not to use it or routes to alternatives (e.g., use list_concepts to enumerate contents vs. this for aggregates), so the agent must infer the boundary.

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