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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context that answers are grounded in database code searches and active rules—but omits the nondeterministic LLM nature, latency, or what an answer looks like. An output schema exists, so return format is not required 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?

Very short and front-loaded with the core action; no filler sentences. The awkward mid-sentence line break is cosmetic but costs nothing in meaning.

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?

Annotations cover the safety profile and an output schema covers return values, so the main omissions are the two undocumented parameters and the lack of routing guidance against sibling search tools. Adequate but with clear gaps for a question-answering 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 0%, so the description carries the full burden, yet it never explains the required 'query' parameter's expected form or what 'repo_path' does (scope limiting? defaults to current repo?). The word 'question' loosely maps to 'query' but both parameters are effectively undocumented.

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 (asks) and clearly names the resource (the project LLM assistant) and its grounding sources (database code searches and active rules). This distinguishes it conceptually from raw-search siblings like search_code, but it never explicitly contrasts them, so it stops short of a 5.

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

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

The phrase 'about the project code' implies the context for use, but there is no when-to-use guidance, no statement about when to prefer search_code/find_related_files instead, and no prerequisites mentioned. Usage is only inferable.

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 this as a safe read (readOnlyHint=true, openWorldHint=false). The description adds a genuinely useful behavioral detail not in the annotations: long result sets are offloaded to a brain:// resource rather than returned inline. However, it is cryptic about what that resource is or how the caller should consume it, limiting the value.

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

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

A single compact sentence with the core action front-loaded and no filler. It is efficient, though bordering on terse enough to obscure meaning.

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

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

For a tool with no output schema, 0% parameter coverage and only minimal annotations, the description omits what 'related' means, what the result set contains, how the brain:// resource is surfaced, and the role of repo_path. It is not sufficient for confident 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 description coverage is 0%, so the description must carry parameter meaning. It obliquely covers file_path ('a path') but says nothing about repo_path, its default, or why a caller would supply one — half the parameters remain undocumented in both places.

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

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

States a concrete action and resource: finding graph neighbours of a path, with the traversal order (direct then indirect) spelled out. It does not, however, distinguish itself from likely siblings such as impact_analysis or search_code, and 'Graph neighbours' is jargon the agent must interpret.

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

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

There is no statement of when to reach for this tool versus alternatives, nor any prerequisite (e.g. does it need the file to be indexed?). 'Direct then indirect' describes traversal order, not usage context, so the agent is left to infer when this is the right call.

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 safety profile is covered. The description adds that the job is asynchronous and that both status and result are returned, which is modest but genuine value beyond the annotations; it says nothing about polling behavior, job states, or failure modes.

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

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

A single, front-loaded sentence with no filler. It is appropriately sized for a simple lookup, though its brevity is partly under-specification rather than pure economy.

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

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

With no output schema, the description carries the burden of explaining return values, and 'status and result' is only a minimal sketch — no indication of status values or result shape. Combined with the undocumented job_id, the definition is adequate but leaves clear gaps.

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

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

The single required parameter job_id has 0% schema description coverage and the description adds no information about it — not its format, nor which prior call produces it. The description does not compensate for the schema gap.

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

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

States a specific verb ('Read') and resource ('asynchronous Brain job') plus what is retrieved (status and result). It clearly identifies the operation, though it does nothing to distinguish itself from the surrounding sibling tools.

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

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

The word 'asynchronous' hints that this is used after kicking off a job, but there is no explicit when-to-use, no prerequisite stating where a job_id originates, and no named alternative. The agent must infer the entire usage 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a genuinely non-obvious behavioral trait: long-tail results are offloaded to a 'brain:// resource'. That is useful beyond the annotations, but it is cryptic — it never says how to retrieve that resource or when truncation kicks in.

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?

Eleven words in one semicolon-joined sentence with no padding, and the primary output content is front-loaded before the resource-offload caveat. It is efficient, though the terseness borders on under-specification rather than true economy.

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 and 0% parameter coverage, the description must explain what comes back and how to invoke it; 'affected components and risks' is the only glimpse of the return shape. Nothing addresses repo_path, output structure, or size expectations beyond the passing brain:// remark.

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

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

Schema description coverage is 0% across both parameters, so the description carries the full burden. It loosely maps 'a change' to change_request but offers no format, source, or content expectations, and repo_path is never mentioned at all despite being relevant to how the analysis is scoped.

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

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

The fragment 'Affected components and risks for a change' names the resource (impact findings) and the trigger (a change), which separates it from the record_* and prepare_* siblings. However, it is a noun phrase with no verb, so it never actually states what the tool does (compute, analyze, return) — the agent must infer the action from the tool name.

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

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

No when-to-use condition, no prerequisites, and no mention of alternatives such as review_diff or search_code, which are the plausible siblings an agent might confuse this with. The only guidance is an implicit input hint ('for a change'), with nothing telling the agent when this analysis is warranted.

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 reveal readOnlyHint=false, idempotentHint=false and openWorldHint=true, so safety and repeatability are covered. The description adds real context the annotations don't: the work is queued asynchronously and is 'durable' and 'quality-first' (implying a slower, higher-cost path). However it omits what a caller gets back (a job id?) and how to retrieve results, which matters for a non-idempotent queueing operation.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though the efficiency is partly achieved by leaving required information out.

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

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

For an async, non-idempotent job-queueing tool with no output schema and 0% parameter documentation, the description is far too thin: it says nothing about the job lifecycle, result retrieval (a get_background_job sibling exists), or how repeated calls behave.

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

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

Schema description coverage is 0% across three parameters, so the description carries the full burden and gives no meaning for task_description, notify, or repo_path. Parameter names are mildly self-explanatory, which is the only thing preventing a 1.

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 verb 'Queue' and the object 'context pack' are stated, but 'context pack' is undefined jargon and the description never distinguishes itself from the sibling prepare_task_context. An agent cannot tell which of the two preparation tools to pick from the text alone.

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

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

There is no when-to-use guidance, no statement of prerequisites, and no exclusion of alternatives despite prepare_task_context and prepare_deep_context being adjacent siblings. The parenthetical about reranking reads as an implementation note, not selection guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a real behavioral trait beyond that: output is 'bounded' and non-durable ('runtime slices'), with durable artifacts deferred to a separate deep job. That is useful context, though nothing about auth, limits, or return shape is given.

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

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

It is a single short sentence with no wasted words and the runtime/durable distinction is front-loaded. However, the brevity comes at the cost of clarity — the sentence is under-specified rather than genuinely concise.

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 and no parameter documentation, the description carries the full burden and falls short. An agent still doesn't know what 'slices' contain, how large 'bounded' is, or what the required task_description produces.

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

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

Schema description coverage is 0% and the description says nothing about either parameter. The names (task_description required, repo_path optional) are fairly self-explanatory, but the description makes no attempt to explain what a repo_path does or how the task description is used, so it fails to compensate for the coverage gap.

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

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

The description says it 'Returns bounded runtime slices', which is opaque jargon rather than a clear verb+resource statement of what context is prepared for a task. The only concrete signal is the contrast with 'durable packs' / 'explicit deep job', which hints at sibling differentiation (prepare_deep_context) but never states the tool's actual purpose.

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 gestures at an alternative ('durable packs are an explicit deep job'), implying the deep-context tool handles heavier work, but never explicitly says when to choose this tool over prepare_deep_context or any other sibling. An agent must infer the routing rule from a cryptic clause.

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 disclose the key traits (write operation, not read-only, idempotent, non-destructive, closed-world). The description adds only "to the database," which restates persistence without explaining dedup behavior on idempotent writes, whether an existing decision is overwritten, or whether repo_path scopes the record. Little value beyond the annotations.

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

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

A single compact sentence with no filler and the action front-loaded. It is efficient, though the brevity is under-specification rather than disciplined conciseness.

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

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

For a nine-parameter mutation tool with no output schema and zero schema description coverage, one sentence is far from sufficient. An agent cannot tell which fields are required, what values status accepts, or how the affected_* fields relate to repo_path.

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?

Nine parameters with 0% schema description coverage, and the description names none of them — not the required title, nor status, reason, consequences, repo_path, or the three affected_* arrays. With this coverage gap the description must compensate and it does not at all.

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 clear verb+resource ("Records an architectural or design decision") with a domain qualifier that loosely separates it from sibling record-tools. However, it gives no signal for distinguishing a "decision" from record_rule, record_task_lesson, or record_procedure_outcome, so the agent must guess. Adequate but shallow.

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?

No when-to-use guidance, no prerequisites, and no mention of the closely related sibling tools (record_rule, record_task_lesson, record_task_observation) that also write structured records. The agent is left to infer whether a given piece of knowledge is a decision, rule, or lesson.

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=false, idempotent=true, destructive=false, and openWorld=false, so the safety/write profile is covered. The description adds the once-per-task/skill cardinality rule and the retrieval exclusion, which are useful beyond the annotations, but it says nothing about validation failures, required preconditions, or what gets written.

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

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

A single short sentence with no padding, but its brevity comes from under-specification rather than economy. The cardinality rule postfixes the action in a way that reads as a constraint fragment rather than a front-loaded explanation.

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 required parameters, no output schema, no parameter documentation anywhere, and a marker-style description. For a write tool that mutates recorded state, the definition leaves the agent without enough information to invoke it confidently beyond the bare cardinality rule.

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

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

All six parameters (skill_id, task_id, validation_id, outcome enum, artifact_ids, source_refs) have 0% schema description coverage, and the description mentions none of them. For a six-required-parameter tool the description must compensate for the schema gap and does not at all — the agent gets no guidance on id formats, ref semantics, or what to do with validation_id.

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 verb ('record') and a resource ('outcome'), and adds a scoping constraint ('once per task/skill'). However, it never distinguishes this from the four sibling record_* tools (record_task_observation, record_task_lesson, record_decision, record_rule), nor does it say what an 'outcome' is beyond the title's 'skill outcome'.

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 genuine usage rule — record only when an outcome is reported, once per task/skill, and 'never on retrieval' — which is a real when-not constraint. But it names no alternatives and 'retrieval' is left undefined, so the agent must infer what counts as an eligible outcome event.

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

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

Annotations already declare the write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false), so the safety bar is lower. However, the description adds essentially nothing beyond that: it does not say whether this creates or upserts, what happens to an existing rule with the same name, or what permissions are required.

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

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

A single front-loaded sentence with no filler. It is appropriately sized as a sentence, though its brevity comes at the cost of substance rather than being tight-but-complete.

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

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

For an 8-parameter mutation tool with no output schema and no parameter documentation, the description is far too thin. It omits the parameter semantics and repository-scoping mechanics an agent needs to invoke it correctly.

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

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

Schema description coverage is 0% across 8 parameters, so the description carries the full burden, yet it documents none of them. Critical fields such as name, type, status, rule_id, severity, applies_to, and repo_path are left entirely to bare titles with no meaning added.

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 (Record) and a precisely scoped resource (repository-scoped normative rule), which distinguishes it from siblings like record_decision, record_task_lesson, and record_task_observation. It is clear but does not explicitly name or contrast with those siblings, so it stops short of a 5.

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

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

There is no when-to-use, when-not-to-use, or alternative-tool guidance. With eleven record_/prepare_/get_ siblings an agent gets no help deciding whether a normative rule belongs here versus record_decision or record_task_lesson.

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 this is a non-destructive, idempotent write, so the safety profile is covered. The description does hint at a tiered evidence model (L1 auto-captured vs L3 requiring human approval), which is real context beyond the annotations, but it never explains what those tiers mean or what the idempotency_key and validation_id do.

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

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

A single short clause with no filler and the core action front-loaded. It is appropriately sized in form, though that brevity stems partly from saying almost nothing.

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

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

For a 7-required-parameter evidence-recording tool with no output schema and only minimal annotations, the description is far too thin. It omits parameter meanings, the L1/L3 taxonomy, idempotency semantics, and any notion of what constitutes a valid lesson or how the referenced artifacts/validation are resolved.

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?

All 7 parameters are required with 0% schema description coverage, and the description supplies no meaning for any of them — not task_id, category, statement, artifact_ids, validation_id, source_refs, or idempotency_key. With zero structured coverage, the description was the only place to compensate and it does nothing.

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 verb 'capture' plus 'task-owned reported evidence' gestures at a write action, but the object is opaque: 'L1' and 'L3' are undefined jargon, and nothing distinguishes this from siblings like record_task_observation or record_procedure_outcome. An agent cannot tell what a 'task lesson' actually is.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative despite several closely related record_* tools. The clause about L3 needing human approval implies a workflow boundary but never states the condition for choosing this tool.

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

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

Annotations already cover the safety profile (write, non-destructive, idempotent), so the description correctly spends its budget on what annotations cannot express: the record is unvalidated, and consolidation deliberately treats it as weaker evidence requiring more independent sightings before becoming durable memory. That downstream lifecycle behavior is exactly the kind of context an agent needs; only the return/acknowledgement behavior is left unstated.

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

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

Two tight sentences with the core capability front-loaded before the comparative note about record_task_lesson. No filler, though the parenthetical and the 'L1' label add mild noise without adding meaning for an outside caller.

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

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

The lifecycle framing is good and no output schema exists, so nothing more is owed on returns. However, for a five-parameter, four-required write tool with zero schema descriptions, the definition never explains the required inputs, so an agent can call it but cannot call it confidently.

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

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

Schema description coverage is 0% across five parameters, so the description must carry the load, and it does not. It hints that a task is involved (task_id) but says nothing about statement, category, the outcome enum, or what idempotency_key means or how it deduplicates, leaving the agent to guess field content and 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 ('capture an unvalidated observation for a task') and explicitly distinguishes itself from the sibling record_task_lesson by evidence weight. The undefined jargon 'L1' slightly obscures the exact resource being created, but the contrast with the sibling makes selection unambiguous.

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

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

Gives a clear use condition — 'no validation/artifact needed' — and positions itself against record_task_lesson as the lighter-weight alternative. It does not name exclusions against the other record_* siblings (record_decision, record_rule, record_procedure_outcome), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavior beyond that: omitted base resolves from origin/HEAD, and the report tail spills into a brain://payload resource when it exceeds the inline budget. That truncation/resource behavior is exactly the kind of non-obvious detail that helps an agent handle 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.

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

Two short sentences, front-loaded with the core action and the base default. The doubled backtick markup around brain://payload is slightly noisy but costs almost nothing in length.

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 carry the return contract; it partially does by disclosing where an oversized report goes, but it says nothing about the report's format or content, and the head/repo_path semantics are absent for a 0%-coverage schema.

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

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

Schema description coverage is 0% and the schema gives only titles and defaults. The description explains base's default resolution, but head (default 'current') and repo_path receive no explanation in either place, leaving two of three parameters semantically undefined.

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 phrase 'Review changes' names a verb and object, and the name review_diff makes the diff context clear, but the description never says what kind of review occurs (static analysis, LLM critique, lint) or what 'changes' spans. It does not differentiate itself from any sibling; record_* siblings are unrelated but nothing here routes the agent.

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?

No when-to-use guidance, no prerequisites, no alternatives named. The only contextual cue is a default-resolution note, which is parameter behavior rather than usage guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and locality are covered structurally. The description adds the return-shape disclosure ('compact paths/symbols/ranges'), which is genuine value beyond annotations, but says nothing about result limits, ranking, or whether it searches the working tree versus history.

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

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

It is a single compact clause with the return-shape information front-loaded, so there is no wasted padding. But the compression goes past conciseness into under-specification — both halves are fragments ('locator', 'known files can be read locally') that require the reader to supply the subject and the condition.

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, 0% parameter coverage, and a genuinely ambiguous two-parameter query interface, the description should explain at least query form and repo_path behavior. It gestures at the return shape but leaves the interface underspecified for a tool whose main risk is calling it with a malformed query.

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

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

Schema description coverage is 0%, so the description carries the full burden for 'query' and 'repo_path' and supplies nothing: no query syntax, no mention of whether repo_path scopes to a subdirectory or a different checkout. The baseline-3 rule applies only when coverage is high; here the gap is unaddressed.

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 phrase 'paths/symbols/ranges locator' conveys that this finds code locations and returns a compact result set, which is more specific than a bare tautology. But the verb is nominalized ('locator') and the scope (which repository, what kind of query) is never stated, so the agent cannot confidently distinguish it from siblings like find_related_files. The purpose is inferable but vague.

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?

'Known files can be read locally' implicitly routes the agent away from this tool when the file is already identified, which is a real when-not-to-use hint. However, no alternative tool is named, and there is no guidance on what conditions favor this over find_related_files or the context-preparation tools. Usage is implied rather than stated.

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